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. Errors carry a JSON body with a human-readable message.

Code	Meaning
`200`	OK — the request succeeded.
`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.
`402`	Over the free tier (5 create / 5 context fill / 5 standard fill per month) with no payment method.
`404`	Not found — no such resource, or it belongs to another owner.
`409`	Conflict — resource not ready (detection pending) or terminal (session completed).
`413`	Upload too large: file > 10 MB, > 100 pages, > 5 context files, or > 30 MB total.
`422`	Field validation failed.
`429`	Too many requests — rate limited; back off and retry.
`500`	Server error — an unexpected failure; safe to retry.