Getting started
Errors & safe retries
Use endpoint-specific errors and documented idempotency behavior.
Read the endpoint response
Each operation documents its HTTP status codes, response fields and error examples. Retain an available error_code or reference for troubleshooting; remove credentials and personal information before sharing logs.
Choose the next action
| Response | What to inspect |
|---|---|
| 400 | Inputs, formatting and endpoint-specific conditions. Correct the request before resubmitting. |
| 401 / 403 | Authentication, account access and the operation’s permission requirements. |
| 402 | The balance or payment condition described for this operation. |
| 404 | The resource identifier and its availability to this account. |
| 409 | The operation’s documented conflict or state condition. |
| 429 / 503 | The documented rate-limit or temporary-failure response, then a bounded retry strategy. |
Idempotency is operation-specific
Do not assume that every endpoint supports an idempotency key or that the key is always required. Read its request parameters. When supported, retain the same key for an identical retry; do not reuse it for a different business operation.
A network timeout does not prove that a write failed. Reconcile the operation’s state before issuing a new request that might repeat a charge or action.
Webhooks can repeat
Webhook delivery retries use the same event ID. Store that ID and make processing idempotent. This is separate from the idempotency key on an outbound API request.