Error Contract Stable error codes for automation

API error responses are normalized for diagnosis, retries, and support escalation.

All covered routes return a structured error object with a stable code, request_id, retry semantics, and documentation anchor. Use this page as the contract baseline for client-side handling.

Open API Reference Open JSON Catalog

Docs > API & Automation > API Errors

Use this page when automation fails and you need normalized error handling, retry behavior, or support escalation context.

API Overview API Reference Token Guide API Playbooks

Unified Error Envelope

{
  "error": {
    "code": "CWS_RATE_LIMIT_EXCEEDED",
    "message": "Too many admin login requests.",
    "category": "rate_limit",
    "http_status": 429,
    "retryable": true,
    "hint": "Back off and retry with exponential delay.",
    "docs": "/api-errors.html#CWS_RATE_LIMIT_EXCEEDED",
    "request_id": "req_...",
    "trace_id": "req_...",
    "details": { "route": "/api/admin/session/login" }
  }
}

code is the machine-stable branch key. Do not parse message for behavior.
request_id and trace_id are mirrored into response headers: X-Request-Id, X-Trace-Id.
retryable should drive client retry policy, combined with HTTP status and Retry-After if present.

Retry Policy Baseline

Retry only when retryable=true or status is 429/503.
Use exponential backoff (500ms → 1s → 2s → 4s) and stop after 4 attempts.
For 429, respect Retry-After when available.
Always log request_id with route and payload hash for support correlation.

Error Code Catalog (Current)

Code	HTTP	Category	Retryable	Intent
`CWS_RATE_LIMIT_EXCEEDED`	429	rate_limit	true	Request burst protection exceeded.
`CWS_AUTH_UNAUTHORIZED`	401	auth	false	Credential/token not accepted.
`CWS_ADMIN_DB_UNAVAILABLE`	503	dependency	true	Admin data plane unavailable.
`CWS_ADMIN_SESSION_CREATE_FAILED`	500	internal	true	Session persistence failed.
`CWS_VALIDATION_INVALID_PLAN`	400	validation	false	Plan value not in allowed set.
`CWS_VALIDATION_PRICE_ID_NOT_CONFIGURED`	400	validation	false	No mapped price id for requested plan.
`CWS_PAYMENT_API_KEY_MISSING`	503	payment	false	Backend checkout credentials missing.
`CWS_PAYMENT_API_KEY_FORMAT_INVALID`	400	payment	false	API key does not match expected provider format.
`CWS_PAYMENT_PROVIDER_UNREACHABLE`	503	dependency	true	Provider endpoint unavailable.
`CWS_PAYMENT_CHECKOUT_REJECTED`	400	payment	false	Provider rejected checkout creation payload.
`CWS_PAYMENT_RESPONSE_DECODE_FAILED`	400	dependency	true	Provider returned unparsable JSON envelope.
`CWS_PAYMENT_CHECKOUT_URL_MISSING`	400	dependency	false	Checkout URL missing in provider response.
`CWS_INTERNAL_UNEXPECTED`	500	internal	true	Fallback for uncategorized backend failures.

Integration Notes

Prefer branching by error.code first, then fallback to HTTP status classes.
Log X-Request-Id for every non-2xx response and include it in support tickets.
Reference this page anchor directly in operator runbooks (for example #CWS_PAYMENT_PROVIDER_UNREACHABLE).
Machine-readable catalog endpoint: GET /api/errors/catalog.

Endpoint-level handling examples are documented in API Reference, and operational retry/runbook flows are in API Playbooks.

API Reliability

Use stable error codes before production rollout.

Save your first $1,000 before the next billing cycle.

Download Trial Open API Reference