Errors

API v1 returns errors as JSON under the error property:

{
  "error": {
    "code": "api_unauthorized",
    "message": "Authentication required."
  }
}

code is the machine-readable value. message is a short description. Some errors also include details and correlation_id.

Status codes

Use the HTTP status and error.code together:

Status	Meaning
`400`	The request could not be parsed.
`401`	The request has no accepted API credential.
`403`	The credential lacks the required scope or account access.
`404`	The requested resource was not found.
`409`	The requested change conflicts with the current resource state.
`413`	The request body exceeds a request limit.
`415`	A request body does not use an accepted JSON content type.
`422`	The request does not match the endpoint contract.
`429`	A rate limit denied the request.
`500`	The API could not produce a valid response.
`503`	A required service was unavailable.

Each endpoint reference lists the exact error codes it can return.

Correlation IDs

Every API v1 response includes X-Correlation-ID. Error bodies can also include the same value as error.correlation_id. Record the correlation ID with the status code and error.code when you investigate a failed request. Do not log the Bearer credential or response fields that may contain personal data.

Retry decisions

For 429, wait for the number of seconds in Retry-After before retrying.
For 503, do not treat the response as a quota reset. A limiter outage uses rate_limiter_unavailable and does not include Retry-After.
For 401 or 403, correct the credential, scope, or account access instead of retrying the same request.
For 422, correct the request using the endpoint reference.

Read Rate limits for the complete 429 behavior.

Overview

Getting started

Guides

Webhooks

Status codes

Correlation IDs

Retry decisions

​Status codes

​Correlation IDs

​Retry decisions

Status codes

Correlation IDs

Retry decisions