Skip to main content
The API uses HTTP status codes to say whether a request worked: 2xx for success, 4xx for a request that cannot be carried out as sent, and 5xx for a failure on our side. Every 4xx and 5xx response under /v1 has the same JSON body, including the 404 for a path that does not exist.

The Error Object

All six fields are always present. A field with no value is null, never left out.

Handle Errors by Type, then by Code

  • Branch on type first. There are few types and each maps to one way of handling the error.
  • Branch on code where you need more detail.
  • New codes are added over time. When you meet a code you do not know, handle it by its type. A code that has shipped is never renamed and never reused for another meaning.
  • Never branch on message.

Types

Codes

Each heading below is a value of code.

credentials_missing

401 authentication_error. No credentials were provided. A request without an API key normally gets the more specific api_key_missing.

credentials_invalid

401 authentication_error. The credentials provided are not valid. A refused API key normally gets the more specific api_key_invalid.

api_key_missing

401 authentication_error. The request has no API key. Send one in the Authorization header: see Authentication.

api_key_invalid

401 authentication_error. The API key was not accepted. This is the answer for a mistyped key, a key that was never issued, a revoked key and an expired key alike. See When a key is refused.

scope_insufficient

403 permission_error. The key is valid but does not have the scope this request needs. Use a key that has it.

permission_denied

403 permission_error. The key is valid but is not allowed to make this request.

parameter_missing

400 invalid_request_error. A required parameter was not sent. param names it.

parameter_invalid

400 invalid_request_error. A parameter has a value that is not accepted: the wrong type, out of range, or not one of the allowed values. param names it.

parameter_unknown

400 invalid_request_error. The request has a parameter the endpoint does not know. param names it. An unknown parameter is refused, not ignored.

cursor_invalid

400 invalid_request_error. A cursor in starting_after or ending_before was not issued by this list for this request: it was changed, or it came from another list, another account, another set of filters or another sort. param names the parameter that held it. Start the list again without a cursor: the same cursor will not work on a retry. See Pagination.

request_invalid

400 invalid_request_error. The request is invalid in a way that is not about one parameter.

resource_not_found

404 invalid_request_error. The path is a real endpoint, but the resource it names was not found.

route_not_found

404 invalid_request_error. No endpoint matches this method and path. Check the path and the HTTP method against the reference.

resource_conflict

409 invalid_request_error. The request conflicts with the current state of the resource. Fetch the resource, then decide whether the request still applies.

request_unprocessable

422 invalid_request_error. The request is well formed but could not be carried out.

idempotency_key_conflict

409 idempotency_error. The idempotency key was already used with a different request. Use a new key for a new request.

idempotency_key_in_use

409 idempotency_error. An earlier request with this idempotency key is still being processed. Wait, then send the same request again with the same key, following the Retry-After header when the response has one. Do not switch to a new key: that could carry out the write twice.

rate_limit_exceeded

429 rate_limit_error. Too many requests. Slow down and retry later, following the Retry-After header when the response has one.

upstream_unavailable

502 api_error. A service this request depends on is unavailable. A write may still have completed.

request_timeout

504 api_error. The request timed out. A write may still have completed.

service_unavailable

503 api_error. The service is temporarily unavailable. Try again later.

internal_error

500 api_error. Something failed on our side. A write may still have completed. If it keeps happening, contact support with the request ID.

Validation Errors

A request with a missing, invalid or unknown parameter is answered with 400 and one of parameter_missing, parameter_invalid or parameter_unknown.
  • param names the parameter. A nested field is a dot path, such as customer.email. An item of an array is named by its position, such as items.0.quantity.
  • Only the first problem is reported. A request with several invalid parameters gets one error. Fix it and send the request again to see the next.
  • A param longer than 100 characters is cut to 100 and ends in ....

Server Errors

A 5xx response means the failure is not caused by your request. The body has the same shape, with the type api_error, and never contains internal details.
  • Reading (GET): retry, waiting longer between attempts each time, such as 1, 2, 4 and 8 seconds with some random variation, and stop after a few attempts.
  • Writing: do not assume the write failed. After internal_error, request_timeout or upstream_unavailable the change may have been made. Fetch the resource to see its current state before sending the write again.
If a 5xx persists, contact support with the request ID.

Request IDs

Every response under /v1 carries a request ID, whether the request succeeded or failed:
  • in the Request-Id response header, on every response;
  • in error.request_id, on an error.
A request ID is req_ followed by 32 hexadecimal characters. The two places always hold the same value for one response.
  • Log the Request-Id of every response, successes included. It is the quickest way for support to find what happened to one request.
  • Quote it when you contact support. Never send your API key.
  • The ID is created by the API. A request ID that you send, for example in an X-Request-Id header, is not used. To follow a request through your own systems, log your own identifier next to the Request-Id you receive.
  • Each attempt has its own ID: a retried request gets a new one.