Errors

The API uses HTTP status codes to report success or failure. A 2xx response indicates success, a 4xx response indicates a problem with the request or its authorization, and a 5xx response indicates that the service could not complete a valid request.

Resource errors normally use a JSON:API error document. A response can contain more than one error, particularly when multiple request members fail schema validation.

Error attributes

statusstring: The HTTP status code associated with the error.
codestringoptional: A stable, machine-readable code when the operation defines one. Prefer it to parsing title.
titlestring: A short, human-readable summary.
detailstringoptional: A more specific explanation of this occurrence.
sourceobjectoptional: The request member that caused the error, commonly identified by source.pointer.
metaobjectoptional: Operation-specific diagnostic information when safe to return.

HTTP status codes

Status	Meaning
`400 Bad Request`	A query parameter, identifier, or request value is malformed.
`401 Unauthorized`	Authentication is missing or invalid.
`403 Forbidden`	The authenticated principal or external integration cannot perform the operation.
`404 Not Found`	The route or requested resource does not exist in the accessible account scope.
`405 Method Not Allowed`	The route exists but does not support the HTTP method.
`409 Conflict`	The operation conflicts with the resource’s current state.
`415 Unsupported Media Type`	The request did not identify an accepted JSON media type.
`422 Unprocessable Entity`	The document shape or one or more values failed validation.
`429 Too Many Requests`	A rate limit was exceeded.
`500 Internal Server Error`	An unexpected server error occurred.
`501 Not Implemented`	The requested capability is recognized but unavailable.
`503 Service Unavailable`	A temporarily unavailable feature or dependency prevented the operation.

Infrastructure-generated errors, including some 429 responses, might not use the JSON:API envelope. Check the status and response Content-Type before parsing the body.

Retry guidance

Correct 400, 401, 403, 404, 405, 415, and 422 responses before retrying.
Re-read the resource before retrying a 409 because its state might have changed.
For 429, wait for the number of seconds in Retry-After.
Retry transient 5xx responses with exponential backoff and jitter.
Do not automatically retry a write unless the operation is documented as idempotent or your client can prove that repeating it is safe.

Every response includes an X-Request-Id header. Include it when contacting support about an error.

Validation error

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/vnd.api+json
X-Request-Id: 8a7058dd-0688-46ad-a00f-c5f3d0b5157e

{
  "errors": [
    {
      "status": "422",
      "title": "The name field is required",
      "source": {
        "pointer": "/data/attributes/name"
      }
    }
  ]
}

Rate-limit error

HTTP/1.1 429 Too Many Requests
Retry-After: 37
RateLimit: limit=5000, remaining=0, reset=37
X-Request-Id: f53b8cb2-b4af-44e5-ad2a-f42ada372d83