Errors, idempotency and pagination
The error shape, stable codes, safe retries and list pages.
Errors
Every failure, including 404 and 405, returns the same shape, and every response carries a Request-Id header. Codes are stable strings: branch on code, show message to developers, and quote request_id when you contact us.
{
"error": {
"code": "invalid_sha256",
"message": "…",
"field": "sha256",
"request_id": "req_4f0c8e2a9b7d4c1e8a3f6b2d0e9c7a15"
}
}| Status | Meaning and codes |
|---|---|
| 400 | The body is not JSON, or the Idempotency-Key is missing or malformed. |
| 401 | The API key is missing or not valid (missing_api_key, invalid_api_key). |
| 403 | The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable). |
| 404 | No such resource for this key, or no such path. |
| 409 | The resource's state does not allow this (order_not_revisable, quote_already_used, upload_incomplete, too_many_endpoints, endpoint_disabled, delivery_in_flight, payment_method_required, partner_terms_required). |
| 413 | The body is over 2 MiB (body_too_large). It may be refused only after more of it was sent. |
| 415 | The body is not application/json. |
| 422 | The request is invalid; field names the problem, code says what it is. |
| 429 | Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key. |
| 500 | Our error. Retrying is safe with the same Idempotency-Key. |
Other codes in the contract: format_unavailable (no price for a format in your mode), idempotency_mismatch, order_released (409, with exception_id), invalid_url and billing_unavailable (503). A 422 names the problem in field.
Idempotency
- Writes that change things require an
Idempotency-Keyheader (1–255 printable ASCII characters);POST /quotesaccepts one. Enabling, disabling and billing setup take none. - Keys are scoped to your account, mode and operation, and kept for 30 days.
- Repeating a request with the same key returns the original response, marked
Idempotent-Replayed: true. - Reusing a key for a different request returns 422
idempotency_mismatch. - A request that failed is not stored, so you can correct it and retry with the same key. Finalize is the exception: see Uploads.
- A 500 is our error. Retrying is safe with the same key.
Generate one key per logical operation (a UUID saved with your own record works well) and reuse it for every retry of that operation.
Pagination
List endpoints return { "object": "list", "data": […], "has_more": … }. Pass limit (1–100) and, for the next page, starting_after with the last id of the page you have. GET /events for one order pages by after_sequence instead.
Other limits
- Each API key can make 300 requests a minute across all endpoints. Past that you get 429
rate_limitedwith aRetry-Afterheader in seconds: wait that long, then retry (with the sameIdempotency-Keyfor writes). - Request bodies are limited to 2 MiB (413
body_too_large). Upload files go to the signed URL, not through the API. - Bodies must be
application/json(415 otherwise). - Paths have no trailing slash:
/orders/is a 404, not a redirect. - Amounts are integers in the currency's minor unit (cents for
usd), with an explicit lowercase currency.