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 theX-Request-IDheader.
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.
| Code | Status | What it means | What to do |
|---|---|---|---|
BAD_ | 400 | The request could not be understood. | Check the request against the endpoint's schema and send it again. |
VALIDATION_ | 400 | One 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_ | 400 | The 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_ | 405 | This endpoint does not accept that HTTP method. | Use a method the endpoint's schema lists. |
NOT_ | 406 | The server cannot answer in the format your Accept header asks for. | Send Accept: application/json. |
REQUEST_ | 413 | The request body is larger than this endpoint accepts. | Send a smaller body, or split the work into several requests. |
UNSUPPORTED_ | 415 | The request body's Content-Type is not one this endpoint reads. | Send Content-Type: application/json. |
UNPROCESSABLE_ | 422 | The request was well formed but cannot be carried out as sent. | Read the error sentence in the body, correct the request and retry. |
NOT_ | 401 | No API key or token was sent. | Send your key in the Authorization header. |
AUTHENTICATION_ | 401 | The 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_ | 403 | Your key is valid but may not do this. | Check the key's scopes and the account it belongs to. |
IP_ | 403 | The 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_ | 404 | Nothing exists at this path, or your key cannot see it. | Check the path and the ID, and that the record belongs to your account. |
CONFLICT | 409 | The request clashes with the record's current state. | Fetch the record again, then retry with its current state. |
GONE | 410 | This endpoint or version has been retired. | Move to the replacement named in the body or the API changelog. |
SYNC_ | 410 | Your 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_ | 402 | This 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_ | 402 | We could not work out what your plan allows for this action. | Retry later. If it keeps happening, contact support with the request_id. |
FEATURE_ | 403 | Your plan does not include this feature. | Read upgrade_denial in the body: it names the plan that unlocks this. Change plan, then retry. |
SUBSCRIPTION_ | 403 | This needs an active subscription. | Read upgrade_denial in the body: it names the plan that unlocks this. Change plan, then retry. |
PURCHASE_ | 403 | This needs a one-off purchase first. | Read upgrade_denial in the body: it names the plan that unlocks this. Change plan, then retry. |
TIER_ | 403 | Your 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_ | 403 | You have reached your plan's usage limit for this period. | Wait for the next period, or change plan. |
GENERATION_ | 403 | You have reached your plan's document generation limit. | Wait for the next period, or change plan. |
AI_ | 403 | There are not enough AI credits left for this request. | Top up AI credits or change plan, then retry. |
STORAGE_ | 403 | Your storage allowance is full. | Delete files you no longer need, or change plan. |
CORPORATE_ | 403 | Every seat on the organisation's plan is taken. | Free a seat or add seats, then retry. |
SEAT_ | 403 | We could not confirm a free seat just now. | Retry with exponential back-off. If it keeps happening, contact support with the request_id. |
RATE_ | 429 | Too 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_ | 500 | Something went wrong on our side. | Retry with exponential back-off. If it keeps happening, contact support with the request_id. |
BAD_ | 502 | A service we depend on gave a bad answer. | Retry with exponential back-off. If it keeps happening, contact support with the request_id. |
SERVICE_ | 503 | The service is temporarily unavailable. | Retry with exponential back-off. If it keeps happening, contact support with the request_id. |
DATABASE_ | 503 | Our service is briefly unavailable. | Wait the number of seconds in the Retry-After header, then retry. |
service_ | 503 | This action is not set up in this environment yet. | Retry later. If it keeps happening, contact support with the request_id. |
STORAGE_ | 503 | File storage is not reachable just now. | Retry with exponential back-off. If it keeps happening, contact support with the request_id. |
DOCUMENT_ | 503 | The document renderer is not reachable just now. | Retry with exponential back-off. If it keeps happening, contact support with the request_id. |
DOCUMENT_ | 503 | The document could not be generated this time. | Retry with exponential back-off. If it keeps happening, contact support with the request_id. |
GATEWAY_ | 504 | A 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_ | 400 | The request failed for a reason on the caller's side. | Read the error sentence in the body, correct the request and retry. |
SERVER_ | 500 | The 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
