Debug API Errors: 401, 402, 429, 5xx Explained
Why API requests fail and how to fix them
When an API request fails, the status code is usually trying to tell you exactly what went wrong. The trick is knowing whether the issue is yours, the provider’s, or just a temporary outage. If you use AI APIs often, learning to debug 401, 402, 429, and 5xx errors will save you hours of trial and error.
This guide explains the most common failure types in simple terms, with practical checks you can do right away. It also shows why a relay like 59API can be a smart choice if you want cheap, pay-as-you-go access to Claude and GPT models without giving up model quality.
Start with the basics: inspect the response
Before changing code, capture the full response. A useful debugging checklist looks like this:
- Status code: What number did the server return?
- Response body: Many APIs include a readable error message.
- Request headers: Check Authorization, Content-Type, and any custom headers.
- Request payload: Make sure the JSON structure matches the API docs.
- Timestamps and request ID: Keep these for support tickets and log correlation.
If your client library hides the error details, enable debug logging. In the OpenAI SDK, Claude Code, Codex, or any other client, logging the raw request and response often reveals the problem immediately.
401 Unauthorized: your auth is wrong
A 401 almost always means the server does not accept your credentials. Common causes include an expired key, the wrong API key copied into your environment, a missing Authorization header, or a malformed bearer token.
What to do:
- Verify the API key is loaded from the expected environment variable.
- Check for accidental spaces or quotes around the key.
- Confirm the auth header format matches the provider’s docs.
- If you recently rotated keys, restart local dev servers and CI jobs.
With 59API, you can point your existing tools at https://api.59api.com and keep the same workflow you already use with OpenAI-compatible SDKs. That makes auth debugging much easier because you are not rewriting your app just to test a different provider.
402 Payment Required: the account or balance is the issue
A 402 usually means you have no usable balance, your billing method failed, or your account has not been activated correctly. In pay-as-you-go setups, this error is often a sign that usage is outpacing the remaining credits rather than a code bug.
What to do:
- Check whether the account has an active balance or billing method.
- Review usage logs to see which requests consumed the most tokens.
- Look for accidental loops that keep sending repeat requests.
- Make sure your app is not retrying a failed request too aggressively.
This is where a low-cost relay can help. 59API is built for cheap, pay-as-you-go access to Claude models like Opus, Sonnet, Haiku, and Fable, plus GPT models, so smaller teams can test more without paying enterprise-level rates. It also offers a referral rebate, which is a nice bonus if you share it with other developers.
429 Too Many Requests: you hit a limit
A 429 means you are sending requests too fast or exceeding a rate limit. This is one of the most common API issues, especially in apps that stream chat responses, run background jobs, or retry failures instantly.
Fix it by doing the following:
- Read the Retry-After header if the API sends one.
- Add exponential backoff, not instant retries.
- Throttle concurrent requests from workers or browser tabs.
- Batch requests when possible instead of firing them one by one.
- Cache repeated prompts or repeated lookups.
If your app uses Claude Code, Codex, or an OpenAI SDK, you can usually add retry and backoff logic in one place. Since 59API is fully compatible with those tools, you can keep your client code familiar while lowering costs and avoiding unnecessary provider changes.
5xx server errors: the problem is usually upstream
5xx codes, such as 500, 502, 503, and 504, usually mean the server or gateway had a problem. These errors are often temporary and may clear up on retry, but they can also indicate a bad upstream dependency, maintenance, or a timeout.
What to do:
- Retry with exponential backoff and a small random delay.
- Check whether the error happens for all requests or only large ones.
- Reduce payload size and prompt length to test whether timeouts are involved.
- Look at provider status pages or incident notices.
- Log the exact model, endpoint, and response headers for later analysis.
Good debugging means separating client mistakes from provider instability. If failures happen across multiple models or tools, the issue is likely in your request setup. If the same request fails only sometimes, you are probably dealing with transient server trouble.
A simple workflow that saves time
Use this sequence whenever an API request fails:
- 1. Confirm the status code.
- 2. Read the error body.
- 3. Compare the request to the docs.
- 4. Retry only when the error is temporary.
- 5. Add better logging so the next failure is easier to diagnose.
If you want a low-cost way to test and debug AI API calls without switching ecosystems, 59API is worth a look. It offers native, official-quality model access through an OpenAI-compatible interface, and its relay setup makes it easy to plug into existing developer workflows. If that sounds useful, sign up and test a few requests with your current client before you change anything in production.
In short: 401 means auth, 402 means billing, 429 means throttling, and 5xx means server trouble. Once you know which bucket the error belongs to, debugging becomes much faster.