Errors & status codes
Emboss uses conventional HTTP status codes. 2xx means success; 4xx means the request was rejected and shouldn't be retried unchanged; 5xx means a server-side problem you can retry. Every call takes an API key, or an OAuth access token from an app you connected (carrying forms:read, forms:write or both), as its Bearer credential. Error bodies come in two shapes: most calls answer { "detail": ... }, where detail is a message or an object with a code; the quote, commit, verify, fax (JSON body), artifact and utility calls answer a problem document with type, title, status and detail.
| Code | Meaning |
|---|---|
200 | OK: the request succeeded. Also the answer to a replay of an earlier request with the same Idempotency-Key. |
201 | Created: a new resource (e.g. a session) was created. |
202 | Accepted: an async job (detection or fill) started. |
400 | Bad request: malformed input, missing file, or invalid JSON. |
401 | Unauthorized: missing or invalid API key or access token. |
402 | No payment method on file, and the request is past the free tier: the monthly free allowance (5 each of creates, context fills, standard fills, verifications, read-backs and packages, each on a document of 5 pages or fewer) is used up, the document is over the page limit, or it is a fax, which always needs a card. The body's detail carries code (over_free_tier, over_page_cap or card_required), message and billing_url, the page to add a payment method. |
403 | Forbidden: an app connected over OAuth whose permission does not cover this call (forms:read to read, forms:write to change anything), a revoked connection, or a wrong proposal token. |
404 | Not found: no such resource, or it belongs to another account. |
409 | Conflict: a resource not ready (detection pending), terminal (session completed), never filled (not_filled), or with work still running on it. |
410 | Gone: the form's documents were deleted under its retention policy; the form's record remains. |
413 | Upload too large: file > 10 MB, > 100 pages, > 5 context files, or > 30 MB total. |
422 | Field validation failed, or a fill from documents was given the blank form itself as a document (body code document_same_as_form), or the PDF's form fields are built in a way that could compromise the service (code pdf_unsafe, message "Emboss does not process PDF files that could compromise the service."; refused before any price, quote, charge or stored file). |
429 | Too many requests: over 60 calls per API key per clock hour that start work (status checks don't count), or a fax or utility limit. The count starts again on the hour; there is no Retry-After header. |
500 | Server error: an unexpected failure; safe to retry. |