Errors
Every error shares one envelope. This page is the status-code glossary for the whole API.
A failed request always returns the same envelope shape, with data: null and a human-readable error string.
JSON
{ "data": null, "error": "Unknown field: job_title"}Two responses add a meta object alongside error with machine-readable detail: the over-quota 402 (your current usage against your cap) and the compliance-pack 409 (which documents are still blocking readiness).
Status-code glossary
4004xx- Malformed body, an unknown field, or a field that failed its own validation. The message names which.
4014xx- Authentication failed — see Authentication. Never 403: this API never distinguishes "wrong permission" from "wrong credential".
4024xx- Reserved for plan limits — your account is over its seat or message quota. The
metaobject carries the figures. 4044xx- Unknown id, someone else’s resource, or the whole API switched off for this deployment (an EMPTY body on that last case).
Not found 4094xx- A conflict — a duplicate candidate, an in-flight Idempotency-Key, or (the pack endpoint) documents not yet all accepted.
4294xx- Rate limit exceeded — see Rate limits. Respect the
Retry-Afterheader.Too many requests — please try again shortly. 5005xx- The write could not be completed or verified. Safe to retry (with the same Idempotency-Key on a create).
5025xx- An upstream fetch (storage or Twilio media) failed. Safe to retry.
5035xx- The service, or a record a read depends on, is temporarily unavailable. Never a confident empty/negative payload — retry shortly.
The two byte-response endpoints (document content, the compliance pack) still return this same JSON envelope on any error status — only a 200 returns raw bytes.