Errors

Every /v1 operation reports failures with one JSON envelope, declared as ApiErrorResponse in the OpenAPI document:

{
  "error": {
    "code": "not_found",
    "message": "Not found"
  }
}

Branch on the HTTP status and code. Codes are stable lowercase snake_case. Messages are safe, human-readable text that may change, so never parse them. Error responses never include internal details, and the X-Request-ID header identifies the request when you report a problem.

Common codes

Mail sending restrictions also use 429, with their own codes. A Retry-After header on a 429 gives the seconds to wait before retrying. Don't retry in a tight loop.

Handle a failure

• A conflict means the resource changed, or the request differs from an earlier one with the same identity. Read current state before deciding what to do; never retry with a new identity or revision just to get past it.
• A timeout or lost response doesn't prove the request failed. Repeat the identical request with the same identity, or read its status. See Operations.
• A permission failure follows the account's current role and each resource's rules. Reconnecting or retrying grants nothing.
• A 429 or 503 is temporary. Resolve any uncertain write before submitting it again.

Feature codes

Each guide documents the codes its operations return:

New codes are added with the features that introduce them. Treat an unrecognized code by its HTTP status.