Skip to main content
Every error uses the same JSON envelope, so you can branch on a stable machine-readable shape instead of parsing messages: 
{
  "error": {
    "type": "invalid_request_error",
    "code": 400,
    "message": "At least one of contact_name, contact_phone, or contact_email is required"
  }
}
  • type — the failure class (see table).
  • code — the HTTP status code (mirrors the response status).
  • message — a human-readable explanation.

​
Status codes & types

HTTPtypeWhen
400invalid_request_errorMalformed body, bad query params, or bulk over the 500-row cap.
401authentication_errorMissing/invalid token or missing x-customer-id.
403authorization_errorKey lacks the required scope, or is locked to a different customer.
404not_found_errorResource (e.g. a webhook id) not found.
409api_errorIdempotency-Key reused with a different body, or a duplicate resource.
429rate_limit_errorRate limit exceeded — see Retry-After.
5xxapi_errorUnexpected server error. Safe to retry with backoff.

​
Handling tips

  • Validation (400) — fix the request; retrying unchanged won’t help. Bulk requests still return 200 with per-row failed results for row-level problems; a 400 means the whole request was rejected.
  • Auth (401/403) — check the token, the x-customer-id, and that your key carries the scope for the endpoint.
  • Conflict (409) — reuse an Idempotency-Key only for the identical retry; use a new key for a new operation.
  • Rate limit (429) — honor Retry-After.