API error format and error codes

Every error response from the API has the same format. Your code should rely on the error code in the error field, not on the text in message – the code stays stable, while the text can change and is translated into the account language.

#Structure of an error response

{
  "error": "validation_failed",
  "message": "Some of the information provided is invalid. Please check and try again.",
  "details": [
    { "field": "title", "reason": "minLength", "message": "…" }
  ],
  "request_id": "6b1f0c2e-…"
}

error

Machine-readable code, for example not_found. For most errors it is also in the X-Error-Code header – but rely on the field in the body.

message

Human-readable description in the account language: with an API key that of the workspace owner, with a connected app that of the person who connected it. Without a valid token – for example 401 from the token check – the language follows Accept-Language, otherwise it is English. The Content-Language header names the language.

details

Only present when there is more to say. For 422 from input validation, a list with field, reason and message for each problem; for 422 from business logic and all other errors, an object, for example with reason, retry_after_sec or a list of issues. When a size is exceeded it contains field, reason and limit, and for 413 request_too_large max_bytes and max_kb. So check whether details is a list.

request_id

The ID of the request. It is also in the X-Request-Id header. Include it when you contact support.

Exceptions: the 429 rate_limited response has the field retry_after_sec instead of details; with 429 and 403 insufficient_scope, request_id is missing from the body. 401 from the token check and 422 from the schema check have no X-Error-Code header, and with the schema check only the top-level message is translated; the texts inside details stay in English. The X-Request-Id header is always set.

#The most important codes

#Reading input errors

With 422 validation_failed, details lists every problem separately: field is the path of the field (with slashes for nested objects, for example theme_config/button_style), reason is the rule that was broken, such as required, minLength, maxLength, enum or additionalProperties. With additionalProperties, the message says which fields are unknown – often a typo in the field name.

#Recommended handling in your code

• 400, 413 and 422: do not retry, fix the request instead
• 401 invalid_token: get a new token once and retry
• 403: do not retry; check the scope, the plan or who is allowed to do this
• 404: check the ID; after a deletion this is normal
• 409: reload the state and decide whether the action is still needed
• 429: wait as long as Retry-After says, then retry – see Rate limits
• 500 and 503: retry a few times with increasing pauses