← Volver a las guías

Fix Common LLM API Errors: Advanced Debugging Guide

Common LLM API Errors and How to Fix Them

Most LLM API failures are diagnosable from three things: the HTTP status code, the provider error body, and the exact request that reached the server. The difficult cases appear when an SDK masks the response, a proxy changes the expected API format, or retry logic turns a temporary failure into duplicated work. This guide covers the most common production errors when calling Claude or OpenAI-compatible models and the fixes that prevent them from recurring.

401 and 403: Authentication, Authorization, and Wrong Base URLs

A 401 Unauthorized response usually means the API key is missing, malformed, expired, or sent in the wrong header. A 403 Forbidden response generally means the key was accepted but cannot access the requested model, organization, region, or account feature.

• Confirm the key is loaded at runtime, not merely present in a local .env file. Log whether the variable exists, but never log the full secret.
• Check the SDK's expected authentication format. OpenAI-compatible clients commonly use an Authorization header with a Bearer token; a Claude-native client may use a different header convention depending on the client and API mode.
• Verify that your configured base URL does not include an unintended version path or duplicate slash. For 59API, use https://api.59api.com as the API base URL, then let a compatible SDK construct its normal endpoint path.
• Make sure the selected model name is available to the account and is spelled exactly as documented by the relay or SDK configuration.

For a fast isolation test, bypass your application framework and send one minimal request with curl or a small SDK script. If that works, the defect is usually environment loading, middleware, or a client configuration override.

400 and 422: Invalid Request Payloads

A 400 Bad Request or 422 Unprocessable Entity means the server understood the request but rejected its shape or values. The leading causes are mixing Claude message formats with OpenAI chat-completions formats, passing unsupported parameters, invalid tool schemas, and malformed JSON.

• Serialize and inspect the final outgoing JSON after your SDK has applied defaults. Do not rely only on the object created in your application code.
• Use one API dialect per request. OpenAI-compatible requests typically use messages with role and content, while Claude-native APIs have their own request conventions.
• Remove optional parameters one at a time. Values such as temperature, max tokens, response format, reasoning controls, and tool-choice fields are not universally supported across models.
• Validate function or tool schemas with a JSON Schema validator before deployment. Require every object schema to declare properties clearly, and avoid unsupported recursive or overly broad schemas.

When structured output fails intermittently, reserve enough output tokens for the entire JSON document and ask the model to return only the required object. Then validate the response server-side and retry a repair request only when validation fails.

429: Rate Limits, Quotas, and Retry Discipline

A 429 Too Many Requests can represent a request-per-minute limit, token-per-minute limit, concurrent-request limit, or exhausted account credit. Treat these differently. Retrying immediately can worsen a rate-limit event and create a queue collapse.

• Read retry-after headers when present and honor them exactly.
• Use exponential backoff with jitter, for example increasing delays with randomized variation. Cap attempts and set a total retry budget.
• Limit concurrency with a semaphore or worker queue. Token-heavy requests often require lower concurrency than short classification requests.
• Track input and output tokens separately. A large prompt can trigger a token limit even when request count is low.
• Assign idempotency keys or persist request state before retries when your workflow triggers side effects, such as sending emails or creating records.

A relay can reduce cost pressure without requiring an application rewrite. 59API offers pay-as-you-go access to official-quality Claude models, including Opus, Sonnet, Haiku, and Fable, plus GPT models, while remaining compatible with OpenAI SDKs, Claude Code, and Codex workflows. That makes it practical to route lower-risk tasks to an economical model and reserve higher-capability models for complex reasoning.

Timeouts, 5xx Responses, and Streaming Disconnects

408, 499, 502, 503, and 504 errors are usually transient, but they are not all safe to retry blindly. A gateway timeout may occur after the upstream model has already started processing. For non-streaming calls, set a client timeout that exceeds normal model latency and retry only requests that are safe to repeat.

For streaming, handle partial output explicitly. Keep the accumulated text, detect the terminal completion event, and mark a response incomplete if the connection closes early. Do not parse partial JSON as final output. Configure proxy and load-balancer idle timeouts to exceed expected stream duration, and ensure your server flushes stream chunks rather than buffering them.

Context Window and Token Budget Errors

Errors mentioning context length, maximum tokens, or prompt size require arithmetic, not guesswork. Your prompt tokens plus requested completion tokens must fit the selected model's context window. Tool definitions, system instructions, prior chat history, and attached content all count.

• Tokenize before sending, then reserve a completion budget appropriate to the task.
• Summarize older conversation turns instead of repeatedly resending the full transcript.
• Trim retrieved documents by relevance and deduplicate overlapping chunks.
• Set max output tokens dynamically based on remaining context, rather than using one fixed value for every request.

Build error handling as an observable system: record status code, provider request ID, model, latency, token counts, retry count, and a redacted error message. With that telemetry, most LLM API incidents become straightforward configuration or capacity fixes. Developers who want a low-cost compatible endpoint for testing and production routing can sign up for 59API and use its referral rebate to lower ongoing spend further.