Errors

What does error code X mean?

Error code X means the request failed for the machine-readable reason returned in error.code; replace X with codes such as VALIDATION_ERROR, UNAUTHORIZED, or RATE_LIMITED and use the table below for the required action. Include the response request ID when contacting support, and retry only errors marked retryable.

Error format

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid value for employee_bands: 'Huge'.",
    "details": [
      {
        "field": "employee_bands",
        "issue": "invalid_enum_value",
        "received": "Huge",
        "expected": ["Small Employers", "SMB Accounts", "..."]
      }
    ],
    "request_id": "req_8f3a2b1c4d5e6f7a"
  }
}

The request_id is also returned in the X-Request-Id response header on every request (including successes). Include it in support requests.

Status codes

Retry strategy

Error detail fields

Issue types

Every error includes a machine-readable issue field. Use it to branch in client code instead of pattern-matching on message.