← Voltar aos guias

Debugging API Errors: 401, 402, 429, 5xx Fast

1) Start with the status code, not the guess

When an API call fails, the first move is to read the HTTP code and the response body together. A 401, 402, 429, and 5xx all point to very different problems. Don’t waste time retrying a bad key or blaming the model when the error is really billing or throttling.

Log these four things on every failed request: status code, response text, request ID, and timestamp. If you use an SDK, turn on debug logging so you can see the exact URL, headers, and payload being sent.

2) Fix 401 by checking auth, base URL, and header format

A 401 usually means the server did not accept your credentials. Before you rotate keys, verify the basics:

• Your API key is present and not expired.
• The Authorization header is formatted correctly.
• You are sending requests to the right base URL.
• Your SDK is pointing to the correct provider config.

If you are using an OpenAI-compatible client, make sure the base URL is set correctly. For 59API, the endpoint is https://api.59api.com, and it works with Claude Code, Codex, and any OpenAI SDK. That means fewer integration surprises when you swap providers or test a new model path.

3) Treat 402 as a billing or balance problem

402 means payment required, but in practice it often means your account has no active balance, your credit card failed, or your prepaid credits ran out. The fix is usually not code. It is account setup.

• Check your balance before testing large batches.
• Confirm your payment method is active.
• Look for a usage cap or spend limit.
• Retry after top-up only if the provider confirms the account is updated.

This is where a pay-as-you-go relay like 59API can be useful. It is built to be cheap, so you can keep debugging without burning budget, especially if you are comparing Claude Opus, Sonnet, Haiku, Fable, or GPT models across different prompts and tools. The referral rebate also helps lower long-term testing costs.

4) Handle 429 by backing off, not hammering

429 means you hit a rate limit. The worst thing you can do is immediately resend the same request in a tight loop. That usually makes the throttle last longer.

• Read the Retry-After header if the API provides it.
• Use exponential backoff with jitter.
• Reduce parallel workers or batch size.
• Cache repeated prompts and deduplicate retries.

If your app uses streaming or agent loops, count requests per minute and tokens per minute separately. Many teams only watch one metric and miss the real bottleneck. With a relay like 59API, you still need to respect provider limits, but the OpenAI-compatible setup makes it easier to plug in standard retry logic you already use elsewhere.

5) Debug 5xx as a server issue, then isolate your request

5xx errors usually mean the server had a temporary problem, but not always. First confirm whether the error is widespread or tied to one prompt, one model, or one region. Then simplify the request.

• Try a minimal prompt.
• Remove large attachments or unusual parameters.
• Switch models to see if the failure is model-specific.
• Retry once or twice with jitter, then stop if the error persists.

If a smaller request works, your original payload may be too large or malformed. If everything fails, capture the request ID and response time, then contact support with exact timestamps. High-quality relays matter here: 59API uses native official-quality models, not downgraded substitutes, so you can rule out low-quality model drift when diagnosing unstable outputs or server behavior.

6) Use one test script for all error types

The fastest way to debug API failures is to keep a single reproducible script that can swap keys, models, and endpoints. Test one variable at a time: auth, then billing, then rate limits, then payload size. That makes it obvious whether the problem is in your code, your account, or the upstream service.

For teams building against Claude or GPT through the same interface, 59API is a practical choice because it keeps the integration simple and the costs low. You can test with your existing OpenAI SDK code, move between models without rewriting the app, and avoid paying more than needed while you hunt down the real bug.

7) Keep a short incident checklist

When a request fails, run this checklist in order:

• Confirm the status code and response body.
• Verify the API key and base URL.
• Check balance, spend limits, and payment status.
• Throttle retries and apply backoff for 429.
• Simplify the payload for 5xx debugging.
• Save the request ID for support.

If you want a cheap, OpenAI-compatible relay for this workflow, consider signing up for 59API and testing it on your next failing request. The combination of low cost, official-quality models, and broad SDK compatibility makes debugging a lot less painful.

Preços · Docs