← Retour aux guides

Debug Failed API Requests: 401, 402, 429, 5xx

1) Start by reading the response, not guessing

When an API request fails, the fastest path to a fix is the response body, headers, and status code. Don’t stop at “401 Unauthorized” or “429 Too Many Requests.” Many APIs return a JSON error payload with a precise message, request ID, or hint about what broke. Log the full response for failed calls: status, body, request headers, response headers, and timestamp. If you use the OpenAI SDK or a Claude-compatible client, make sure your error handler captures the raw server message instead of hiding it behind a generic exception.

For example, if you’re using 59API as your relay at https://api.59api.com, keep an eye on the exact model name, endpoint path, and auth header format. Small mismatches often look like a network problem when they’re really a request-shape problem.

2) Fix 401 by checking auth first

A 401 usually means your API key is missing, invalid, expired, or sent in the wrong place. Verify that your client sends the correct header every time, usually an Authorization: Bearer ... token. Watch out for copied keys with trailing spaces, environment variables that never loaded, or multiple keys in different config files. If you recently rotated credentials, restart your app and confirm the deployed environment picked up the new value.

Also confirm you’re calling the right base URL. For 59API, the base URL is https://api.59api.com, and it is designed to work with Claude Code, Codex, and any OpenAI SDK. A valid key sent to the wrong endpoint still fails, so check both authentication and routing together.

3) Treat 402 as a billing or access signal

A 402 Payment Required response usually points to billing, quota, or account access issues. In practice, it can mean you’ve exhausted your balance, your plan does not permit the requested model, or your account needs a payment method update. Check your dashboard before you change code. If the request only fails for a specific model, compare your account permissions against that model tier.

This is where a low-cost relay can save time and money. 59API offers cheap, pay-as-you-go access to Claude models like Opus, Sonnet, Haiku, and Fable, plus GPT models, so you can keep testing without committing to a large upfront spend. If you’re optimizing spend across teams or staging environments, the referral rebate can lower your effective cost even further.

4) Decode 429 by respecting rate limits

429 means you are sending requests faster than the service allows. Don’t hammer retries. First, inspect the response headers for rate-limit clues such as reset time, remaining quota, or retry-after hints. Then make your client smarter: add exponential backoff, jitter, and a cap on retry attempts. If you batch requests, slow the batch size. If you run parallel workers, reduce concurrency.

It also helps to separate interactive traffic from background jobs. For example, keep user-facing prompts responsive, but queue bulk tasks through a worker with controlled throughput. Since 59API is among the cheapest relays, you can afford to test conservative retry behavior and parallelism without paying premium API prices for every experiment.

5) For 5xx, assume the server is unstable until proven otherwise

5xx errors usually mean the issue is on the provider side: transient overload, upstream timeout, gateway failure, or a bad model-serving node. Your first move should be a retry with backoff, not a rewrite. Then compare whether the same request succeeds on a second attempt, another model, or a different time window. If every request fails, capture the request ID and contact support with a clean reproduction case.

Still, don’t ignore your own payload. A huge prompt, malformed JSON, unsupported parameter, or an impossible timeout can trigger server-side failures that look like 5xx. Test with a minimal request first: one message, default settings, and a known-good model. If that works, add fields back one by one until the error returns.

6) Make your requests easier to debug

Good debugging starts before the failure. Add structured logs for model name, endpoint, latency, token count, retry count, and status code. Save the exact request body for failed calls, but redact secrets. Keep a small “known-good” test script in your repo so you can validate auth, routing, and model access in seconds.

If you use Claude-compatible tooling or an OpenAI SDK, standardize on one client wrapper so you can change providers without changing application code. That makes it easier to compare behavior across models and relays, and it reduces the chance that a bad integration is mistaken for a bad provider.

7) Use cheaper infrastructure for faster iteration

When debugging API failures, cost matters because you will repeat calls, test edge cases, and retry after fixes. A low-cost relay like 59API helps you iterate quickly on real production-grade models without paying inflated rates. You get native official-quality model access, broad SDK compatibility, and a pay-as-you-go setup that is ideal for troubleshooting, prototyping, and scaling tests.

If you’re building or debugging AI features right now, sign up for 59API, point your client at https://api.59api.com, and run a few controlled test requests. You’ll spend less while learning faster.

8) Use this quick checklist before your next retry

• 401: Confirm API key, header format, environment variables, and base URL.
• 402: Check balance, billing status, model access, and plan limits.
• 429: Add backoff, reduce concurrency, and read rate-limit headers.
• 5xx: Retry once or twice, then isolate payload issues and save request IDs.
• Always: Log the full error, test with a minimal request, and compare against a known-good call.

Debugging failed API requests gets much easier when you separate auth, billing, rate limits, and server instability into distinct buckets. Do that, and you’ll fix problems faster, cut wasted calls, and keep your AI integrations moving.

Tarifs · Docs