Errors and retries

Read an error response

{
  "error": {
    "code": "FIELD_REQUIRED",
    "message": "A required field is missing.",
    "request_id": "req_EXAMPLE_ONLY",
    "retryable": false,
    "field_errors": [
      {
        "field": "target",
        "code": "FIELD_REQUIRED",
        "message": "target is required."
      }
    ],
    "docs_url": "https://docs.example.com/errors/field-required"
  }
}

The example message is illustrative. Branch on error.code rather than human-readable wording, and use field_errors to locate invalid inputs.

Safe retry sequence

1. Read the actual error.retryable value. If false, fix the input, permission or stale state instead of blindly repeating the request.
2. If Retry-After is present, wait at least that long. Use bounded attempts and increasing delays, not an infinite tight loop.
3. Preserve the body and idempotency key for retries of one logical operation. After an ambiguous timeout, a new key can create a duplicate operation.
4. IDEMPOTENCY_KEY_REUSED means the key was used with different input: inspect the earlier result and intended operation. IDEMPOTENCY_IN_PROGRESS means processing continues; retry the same request after Retry-After.
5. SDK Queued is not server success. The SDK manages durable retries; do not add an independent infinite network loop in the app.

When requesting help

Include time and timezone, API path and method, HTTP status, error.code, request_id, SDK version and platform. Exclude personal data, full message bodies, passwords, API keys, device/push tokens and invitation/reset links.