Guide

Errors

Recover from API failures using stable codes, request IDs, and explicit retry rules.

On this page

Prerequisites
Read an error
Expected result
Errors
Next step

Prerequisites

Log the HTTP status, stable error code, and request_id. Redact Authorization, cookies, webhook secrets, provider challenges, and customer message content before telemetry leaves your process.

Read an error

json

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "API key request rate limit exceeded",
    "request_id": "00000000-0000-4000-8000-000000000001"
  }
}

Treat messages as human context and codes as program logic. Use the request ID when contacting support.

Expected result

Validation and authorization failures stop immediately. Accepted asynchronous writes return a command identity whose state can be inspected independently.

Errors

Retry 429 after the reset time and transient 5xx responses with bounded jitter.
Do not retry 401, 403, or 422 without changing credentials, entitlement, or input.
Resolve 409 idempotency_conflict by using the original input or a new key.
A 404 may intentionally hide a resource outside the current project.

Next step

Add code-based handling, idempotency keys for writes, and alerts for repeated failures with the same operation.