Reference

Errors

HTTP status codes, error types and error codes returned by the Macaaw Public API.

Successful calls answer with a 2xx status. Errors answer with a 4xx or 5xx status and a JSON body:

402 Payment Required

{
  "type": "limit_error",
  "code": "LIMIT_AGREEMENTS",
  "detail": "Your plan includes 3 documents for signature a month, and they have all been used.",
  "info": {
    "limit": 3
  }
}

type — the broad class, for your error handling.
code — the specific reason, stable over time (the same codes the website uses).
detail — a plain-English explanation for logs. Do not parse it; it may change.
info (sometimes) — machine-readable extras such as reason, limit, fields (validation problems by path) or roles.

Error types#

type	Typical status	Meaning
`request_error`	400, 413, 415, 422	The request is invalid: a missing or wrong field, a file that is too large, of the wrong type or cannot be read.
`authentication_error`	401	Missing, malformed, unknown or revoked API key. See Authentication.
`permission_error`	403	The key is valid but not allowed: live key without API access, suspended account, team role, sandbox recipient rule.
`not_found`	404	No such object — or it belongs to another workspace, or to the other environment (live vs sandbox).
`conflict`	409	The object is in the wrong state, e.g. sending a document that is not a draft, or a repeated `Idempotency-Key` with a different body.
`limit_error`	402, 403, 409	A plan limit is used up (agreements this month, signers, OCR pages, credits…) or an account limit is reached (API keys, webhooks).
`rate_limit`	429	Too many requests. Wait for `Retry-After` seconds. See Rate limits.
`server_error`	500, 502, 503, 504	Something failed on our side. Retry with backoff; calls with an Idempotency-Key are safe to repeat.

HTTP status codes#

Status	Meaning
200 OK	Success.
201 Created	A document, task, webhook subscription or session was created.
204 No Content	Deleted.
400 Bad Request	Validation failed. The detail names the field.
401 Unauthorized	No valid API key.
403 Forbidden	Not allowed for this key, plan or account.
404 Not Found	Unknown id or path.
409 Conflict	Wrong state for this action.
413 Payload Too Large	File above your plan’s size limit (25 MB in the sandbox) or JSON above 2 MB.
422 Unprocessable Entity	The file is damaged, password-protected or otherwise cannot be processed.
429 Too Many Requests	Rate limit reached; see `Retry-After`.
5xx	Server error; retry later.

Common codes#

code	What to do
`VALIDATION`	Fix the request; the detail says which field.
`API_KEY_INVALID`	Check the Authorization header and that the key has not been revoked.
`OAUTH_NOT_SUPPORTED`	Use `Authorization: API-Key …`; Bearer tokens are reserved for OAuth.
`SANDBOX_RECIPIENT`	Sandbox documents go only to your own email domain.
`IDEMPOTENCY_CONFLICT`	The Idempotency-Key was used for a different request, or the first request is still running.
`REQUEST_TOO_LARGE`	JSON over 2 MB, or an upload over your size limit.
`API_ACCESS_REQUIRED`	Live keys need a plan with API access. Use a sandbox key or upgrade.
`INVALID_STATE`	Read the object’s status first; e.g. only drafts can be sent.
`LIMIT_AGREEMENTS`	Monthly agreement allowance used up.
`LIMIT_SIGNERS`	Too many signers for your plan.
`LIMIT_FILE_SIZE`	File too large for your plan.
`FILE_DAMAGED`	The PDF cannot be read.
`FILE_PASSWORD`	Remove the password from the PDF first.
`RATE_LIMITED`	Wait `Retry-After` seconds.