API errors and request IDs

What an error from our APIs tells you, and what to do next

Last reviewed

The error body

Our Portfolio, Professional and Corporate APIs answer an error with the same JSON body and a matching HTTP status:

  • error: a short, human-readable message. Show it in your logs, not to your own users, as its wording can change.
  • status_code: the HTTP status again, for tools that lose the status line.
  • error_code: a code your program can branch on, listed below. Branch on this, not on the message.
  • request_id: the ID of this exact call, also sent as the X-Request-ID header.

A validation error also names each field that failed and why. A plan error adds upgrade_denial, naming the plan that unlocks the feature.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-Request-ID: 3f2a9c4e-0d1b-4c7e-9a52-6b8e1f0c2d47

{
  "error": "Request was throttled. Expected available in 30 seconds.",
  "status_code": 429,
  "error_code": "RATE_LIMITED",
  "request_id": "3f2a9c4e-0d1b-4c7e-9a52-6b8e1f0c2d47"
}

Error codes

These are the codes every external API can send. One endpoint may also send a code of its own for a rule only it has; that code is described in the endpoint’s OpenAPI reference.

CodeStatusWhat it meansWhat to do
BAD_REQUEST400The request could not be understood.Check the request against the endpoint's schema and send it again.
VALIDATION_ERROR400One or more fields failed validation. The body names each field and why.Fix the fields listed in the body and send the request again.
PARSE_ERROR400The request body is not valid JSON (or not the declared content type).Check the request against the endpoint's schema and send it again.
METHOD_NOT_ALLOWED405This endpoint does not accept that HTTP method.Use a method the endpoint's schema lists.
NOT_ACCEPTABLE406The server cannot answer in the format your Accept header asks for.Send Accept: application/json.
REQUEST_TOO_LARGE413The request body is larger than this endpoint accepts.Send a smaller body, or split the work into several requests.
UNSUPPORTED_MEDIA_TYPE415The request body's Content-Type is not one this endpoint reads.Send Content-Type: application/json.
UNPROCESSABLE_ENTITY422The request was well formed but cannot be carried out as sent.Read the error sentence in the body, correct the request and retry.
NOT_AUTHENTICATED401No API key or token was sent.Send your key in the Authorization header.
AUTHENTICATION_FAILED401The key or token was sent but is not valid: wrong, expired or revoked.Check the key in your developer settings, or create a new one.
PERMISSION_DENIED403Your key is valid but may not do this.Check the key's scopes and the account it belongs to.
IP_NOT_ALLOWED403The key or token is valid, but its owner has limited it to a list of IP addresses and this request came from outside that list.Send the request from an allowed address, or ask the credential's owner to add this address to its allowlist.
NOT_FOUND404Nothing exists at this path, or your key cannot see it.Check the path and the ID, and that the record belongs to your account.
CONFLICT409The request clashes with the record's current state.Fetch the record again, then retry with its current state.
GONE410This endpoint or version has been retired.Move to the replacement named in the body or the API changelog.
SYNC_WINDOW_EXPIRED410Your updated_since value is older than the window we keep deletions for, so a delta from it could miss records.Run a full sync without updated_since, then carry on from the new high-water mark.
PAYMENT_REQUIRED402This needs a paid plan or more allowance.Read upgrade_denial in the body: it names the plan that unlocks this. Change plan, then retry.
ENTITLEMENT_UNRESOLVED402We could not work out what your plan allows for this action.Retry later. If it keeps happening, contact support with the request_id.
FEATURE_NOT_IN_PLAN403Your plan does not include this feature.Read upgrade_denial in the body: it names the plan that unlocks this. Change plan, then retry.
SUBSCRIPTION_REQUIRED403This needs an active subscription.Read upgrade_denial in the body: it names the plan that unlocks this. Change plan, then retry.
PURCHASE_REQUIRED403This needs a one-off purchase first.Read upgrade_denial in the body: it names the plan that unlocks this. Change plan, then retry.
TIER_CAPACITY403Your plan's capacity for this is used up.Read upgrade_denial in the body: it names the plan that unlocks this. Change plan, then retry.
USAGE_LIMIT_EXCEEDED403You have reached your plan's usage limit for this period.Wait for the next period, or change plan.
GENERATION_LIMIT_EXCEEDED403You have reached your plan's document generation limit.Wait for the next period, or change plan.
AI_CREDITS_INSUFFICIENT403There are not enough AI credits left for this request.Top up AI credits or change plan, then retry.
STORAGE_QUOTA_EXCEEDED403Your storage allowance is full.Delete files you no longer need, or change plan.
CORPORATE_SEATS_FULL403Every seat on the organisation's plan is taken.Free a seat or add seats, then retry.
SEAT_CHECK_UNAVAILABLE403We could not confirm a free seat just now.Retry with exponential back-off. If it keeps happening, contact support with the request_id.
RATE_LIMITED429Too many requests in this window.Wait the number of seconds in the Retry-After header, then retry. X-RateLimit-Remaining shows what is left.
INTERNAL_ERROR500Something went wrong on our side.Retry with exponential back-off. If it keeps happening, contact support with the request_id.
BAD_GATEWAY502A service we depend on gave a bad answer.Retry with exponential back-off. If it keeps happening, contact support with the request_id.
SERVICE_UNAVAILABLE503The service is temporarily unavailable.Retry with exponential back-off. If it keeps happening, contact support with the request_id.
DATABASE_UNAVAILABLE503Our service is briefly unavailable.Wait the number of seconds in the Retry-After header, then retry.
service_misconfigured503This action is not set up in this environment yet.Retry later. If it keeps happening, contact support with the request_id.
STORAGE_UNAVAILABLE503File storage is not reachable just now.Retry with exponential back-off. If it keeps happening, contact support with the request_id.
DOCUMENT_RENDERER_UNAVAILABLE503The document renderer is not reachable just now.Retry with exponential back-off. If it keeps happening, contact support with the request_id.
DOCUMENT_GENERATION_FAILED503The document could not be generated this time.Retry with exponential back-off. If it keeps happening, contact support with the request_id.
GATEWAY_TIMEOUT504A service we depend on took too long to answer.Retry with exponential back-off. If it keeps happening, contact support with the request_id.
CLIENT_ERROR400The request failed for a reason on the caller's side.Read the error sentence in the body, correct the request and retry.
SERVER_ERROR500The request failed for a reason on our side.Retry with exponential back-off. If it keeps happening, contact support with the request_id.

The full list is also served as JSON at /api/v1/api-errors/, so your own tools can look a code up.

Getting help with a failed call

Log the X-Request-ID header (or the request_id field) of every failed call. If you need our help, send it to us through the contact form with the time of the call. The ID lets our support team find that exact call without you sharing your API key, which you should never send to anyone.

For a 429, wait as the rate limits guide explains before you retry.

Can’t find what you’re looking for?

Our support team is here to help. Contact us and we’ll get back to you as soon as possible.

Contact us

We use cookies to improve your experience. See our Cookie policy (opens in a new tab) for details.