401, 403, 429 or 503: where to start with an API error
Separate authentication, permissions, rate limits and service availability before retrying.
On this page
The short answer
Start with the HTTP status and response body. A 401 points to missing or invalid authentication; 403 indicates refusal to allow access. A 429 signals too many requests, while 503 indicates that the service is currently unavailable.
Collect enough evidence before changing anything
Record the method, endpoint, status, time and request ID, if available. Read the error body and relevant response headers. Also identify who generated the response: an API application, gateway or protective proxy may reject the request for different reasons.
Reproduce with one minimal request rather than a stream of retries. Compare it with a known working request and change one factor at a time. Do not paste Authorization headers, cookies or full credential-bearing URLs into screenshots and logs; the request ID is usually safer to share.
Check the cause before retrying
For 401, inspect the credential and authentication scheme. For 403, check permissions and the resource being requested. Retrying the same forbidden request usually changes nothing.
401 and 403 need different investigations
For 401, check that the credential exists, has not expired and uses the expected scheme, such as Bearer. A conforming 401 response includes WWW-Authenticate. If a supported refresh flow is available, refresh once and retry once; an endless refresh loop will not fix a wrong credential.
For 403, check the account’s role, requested resource and API scope. The same user may read a resource but lack permission to modify it. A proxy may also block a location or IP. Do not assume that creating another token grants a missing permission; consult the error body and the service’s rules.
Use controlled retries
For 429 or 503, inspect Retry-After if provided and use bounded backoff. Only retry an operation when repeating it is safe; a timed-out write might already have succeeded. Keep request IDs for diagnosis and never log credentials.
Understand what Retry-After asks you to do
A 429 can reflect a per-user, per-IP or shared quota, depending on the service. In the illustrative response below, Retry-After: 30 requests a wait of 30 seconds before trying again. The field may instead contain an HTTP date; account for that form in a real client.
Reduce concurrency and share retry scheduling between workers that use the same quota. For 503, examine service status and gateway health too. Respect Retry-After when present; otherwise use bounded backoff with jitter and a total time budget. Increasing the number of retries during overload can prolong the incident.
HTTP/1.1 429 Too Many Requests
Retry-After: 30A failed response does not always mean a failed operation
Suppose a payment or job-creation request times out after the server accepted it. Repeating it may create a duplicate even if the first response was never received. For writes, use the API’s documented idempotency mechanism or check operation status before resubmitting. Do not invent an idempotency header the API does not support.
A practical client separates permanent authorization problems from temporary failures, limits attempts and records why it stopped. Repeating a GET is usually simpler than repeating a POST, but the API contract remains decisive. When escalating, send the time, endpoint, status and request ID with secrets removed.
Things to check
- Read the response body and relevant headers.
- Check whether the operation is safe to repeat.
- Limit attempts and preserve request IDs.
Where this applies
API implementations vary. Their own documentation and error payload take precedence over assumptions based only on the status code.