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
typefirst. There are few types and each maps to one way of handling the error. - Branch on
codewhere 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 ofcode.
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 with400 and one of parameter_missing, parameter_invalid or parameter_unknown.
paramnames the parameter. A nested field is a dot path, such ascustomer.email. An item of an array is named by its position, such asitems.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
paramlonger than 100 characters is cut to 100 and ends in....
Server Errors
A5xx 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_timeoutorupstream_unavailablethe change may have been made. Fetch the resource to see its current state before sending the write again.
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-Idresponse header, on every response; - in
error.request_id, on an error.
req_ followed by 32 hexadecimal characters. The two places always hold the same value for one response.
- Log the
Request-Idof 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-Idheader, is not used. To follow a request through your own systems, log your own identifier next to theRequest-Idyou receive. - Each attempt has its own ID: a retried request gets a new one.