Overview API Reference API Explorer Need help?

Handling errors

API clients should be designed to anticipate and smoothly manage temporary server issues and rate limiting. These errors are returned through standard HTTP status codes and a JSON-formatted error response.

HTTP status codes

Below is a table listing and explaining the HTTP status codes that may be returned.

Code	Message	Description
400	Bad Request	The request is malformed or incorrect and cannot be processed.
401	Unauthorized	Authentication information is either missing or invalid for the resource.
402	Payment Required	Payment requirements for the API have not been met.
403	Forbidden	Access to the requested resource is denied. The user may not have sufficient permission or the necessary license.
404	Not Found	The requested resource does not exist.
405	Method Not Allowed	The HTTP method used in the request is not allowed for the resource.
406	Not Acceptable	The service does not support the format specified in the Accept header.
409	Conflict	The current state conflicts with what the request expects.
410	Gone	The requested resource is no longer available on the server.
411	Length Required	The request requires a Content-Length header.
412	Precondition Failed	A precondition provided in the request, such as an if-match header, does not match the resource's current state.
413	Request Entity Too Large	The size of the request exceeds the maximum allowable limit.
415	Unsupported Media Type	The content type of the request is in a format not supported by the service.
416	Requested Range Not Satisfiable	The specified byte range is invalid or unavailable.
422	Unprocessable Entity	The request cannot be processed because it is semantically incorrect.
423	Locked	The resource being accessed is locked.
429	Too Many Requests	The client application has been throttled and should not attempt to repeat the request until some time has passed.
500	Internal Server Error	An internal server error occurred while processing the request.
501	Not Implemented	The requested feature is not implemented.
503	Service Unavailable	The service is temporarily unavailable due to maintenance or overload. You may retry the request after a delay, which may be specified in a Retry-After header.
504	Gateway Timeout	The server, acting as a proxy, did not receive a timely response from the upstream server needed to complete the request.
507	Insufficient Storage	The maximum storage quota has been reached.
509	Bandwidth Limit Exceeded	The application has been throttled for exceeding the maximum bandwidth limit. The request can be retried after some time has passed.

The error response is a JSON object containing a single property named error, which includes all the error details. You can use the information from this object either as a supplement to or instead of the HTTP status code. Below is an example of a complete JSON error body:

{
  "error": {
    "code": "BadRequest",
    "message": "The request is invalid.",
    "innerError": {
      "request-id": "3a8c04bd-e29a-4c42-9bb1-a45474b459a9",
      "date": "2024-06-16T00:00:00Z"
    }
  }
}

Error resource type

An error resource is returned whenever an error occurs during the processing of a request.

Properties

The code property provides a machine-readable identifier that categorizes the type or class of error encountered during the execution of a request.

The message property within an error resource provides a human-readable explanation or description of the encountered error. It aims to convey useful information about what went wrong during the processing of a request or operation. However, you should not rely programmatically on the exact content of this message

The innerError object may recursively include additional innerError objects with more specific error code properties. When handling an error, applications should iterate through all available nested error codes and use the most detailed one they understand.

The optional details error property contains additional information about specific errors that occurred within the context of the main error. This property is structured as an array of JSON objects, each following the same format as the primary error object. Each object in the "details" array provides more granular details about individual errors, which can include specific error codes, messages, and possibly nested "innerError" objects for deeper error context.

Rate limiting

We return a 429 Too Many Requests response when you've exceeded a rate limit. Consult the Retry-After response header to determine how long to wait (in seconds) before retrying the request.

Plan ahead to gracefully handle the failure modes that API backpressure will exert on your integration. Multiple rate limits are in effect, e.g. for GET vs POST requests and per-second/hour/day limits, and they're adjusted dynamically, so responding to them dynamically is essential, particularly at high traffic levels.

For a sense of scale, the first rate limit you'll commonly encounter is currently 50 requests per 10 second period per IP address.

5xx server errors

If API service is having trouble, you will get a response with a 5xx status code indicating a server error. 500 (Internal Server Error), 502 (Bad Gateway), 503 (Service Unavailable), and 504 (Gateway Timeout) may be retried with exponential backoff.

404 Not Found

API requests may 404 due to deleted content, an inactive account, missing user permissions, etc. Detect these conditions to give your users a clear explanation about why resources can not be found or interacted. Do not automatically retry these requests.

Methods

Resources