# Errors, retries and idempotency

Recover from errors without creating duplicate guests or overwriting newer changes.

## Use the code and request ID

400 means invalid input or cursor. 401 means the key cannot authenticate. 402 means production entitlement or guest allowance prevents the action. 403 means missing scope or authority. 404 means the requested resource is not accessible. 409 means an idempotency, status or version conflict.

413 means the request exceeds the body limit. 429 means a rate limit was reached; honor Retry-After. For a 5xx response or lost connection, retry a retryable write only with the same Idempotency-Key and body. Give support the requestId, timestamp and operation, never a secret or guest request body.

```json
{"error":"Human-readable message.","code":"STABLE_CODE","requestId":"REQUEST_ID"}
```

## Persist one key per logical action

Creates and supported retryable writes require Idempotency-Key, up to 128 characters. Persist it before sending the action. A completed retry returns the saved minimal result after current authorization and entitlement checks.

Reusing a key with a different canonical payload returns 409. Completed results are retained for 30 days; after the retention window, do not assume a retry will still be deduplicated. Use your source record and an exact external-reference lookup to investigate before recreating an old action.

## Treat conflicts as decisions

A request already in progress can return a conflict; wait and retry with the same action identity. A stale expectedStatus or expectedVersion requires a new lookup and a decision about whether the original action is still valid.

Do not automatically retry every 4xx response. Back off with jitter for transient failures, honor the bounded server retry guidance, and keep a finite retry budget in your integration.