error.code. For each error, you do one of three things: fix the request, send the same request again with the same key, or send a new request with a new key.
1. Log the request ID
Every response from the API carries anx-request-id header, errors and successes alike. The exception is a request too malformed for the API to read, such as one with oversized headers, which our web server answers before the API sees it. Log it with your own record of the request. It’s the first thing we ask for when you report a problem.
2. Branch on the code
Readerror.code, never message: message is written for people and can change. type groups codes into categories. The error reference lists every code with its status and type.
Three fields add detail when they apply:
3. Decide: fix, retry or resend
What decides it is whether we stored your request. The idempotency page says, code by code, whether we did and what to do. When a response carries aRetry-After header, wait that many seconds before you send the request again.
4. Back off between retries
A5xx without a Retry-After header doesn’t say how long to wait, so back off:
- Wait 1 second before the first retry.
- Double the wait after each failure, and add a random jitter to it, so your retries don’t arrive in step with other clients’.
- Wait no more than 60 seconds between attempts.
- After about 5 minutes of failures, stop. Establish the outcome of the request before you do anything else: retrieve the object if you have its
id, or list by yourclient_reference. If the outcome is still unclear, report the problem.
Idempotency-Key, every retry uses the same key, so however many times you retry, the request is done once.
5. Keep a default for unrecognised codes
We can add codes tov1 (see Versioning), so give every status a safe default:
For what a specific error means on your screen, see Troubleshooting.