Handle rate limits and server errors

Handle a 429 response

A rate-limited request returns 429 Too Many Requests with detail.status set to rate_limit_exceeded. Read the response headers before retrying:

• Retry-After gives the minimum wait in seconds for a rejected request.
• X-RateLimit-Limit reports the bucket limit.
• X-RateLimit-Remaining reports the remaining requests.
• X-RateLimit-Reset reports when the bucket resets.

Wait for Retry-After, then retry with exponential backoff and jitter. Reduce parallel requests and queue work instead of sending a burst as soon as the window resets.

Handle server errors

For a 500 response, the public body contains a generic error and a request_id; internal exception details are not returned. A 503 can indicate that a required service is temporarily unavailable.

Retry read-only requests with a bounded backoff. Before retrying a create, update, payment, or other state-changing request, determine whether the first attempt completed. A timeout or 5xx response does not prove that a mutation failed, and an immediate repeat can duplicate work.

Preserve diagnostics

Record the timestamp, method, path, status, response body, and X-Request-Id. Never log the x-api-key value. Stop automatic retries after a small bounded number of attempts and surface the failure for review.