← Back to all guides

Common LLM API Errors: Fixes and Provider Trade-Offs

Why LLM API Errors Need a Systematic Approach

LLM API failures often look similar in application logs, but a 401 authentication error, a 429 rate-limit response, and a malformed tool-call request have very different fixes. The fastest way to debug is to record the HTTP status, response body, request ID, model name, endpoint, and token usage for every failed request. Then separate problems caused by your client code from problems caused by account limits, model capabilities, or an API relay configuration.

Direct model-provider APIs can offer provider-specific features and documentation, but they may require separate accounts, billing setups, SDKs, and rate-limit strategies. A compatible relay can simplify those operational concerns. For example, 59API provides pay-as-you-go access to official-quality Claude and GPT models through https://api.59api.com, with compatibility for OpenAI SDKs, Claude Code, and Codex workflows. The trade-off is that developers must carefully use the relay's documented base URL, supported model IDs, and authentication format rather than assuming every provider-specific endpoint behaves identically.

401 and 403 Errors: Authentication vs Authorization

A 401 Unauthorized response usually means the API key is missing, expired, malformed, or sent in the wrong header. A 403 Forbidden response usually means the key is valid but cannot access the selected model, organization, feature, or account state.

• Check the header: For OpenAI-compatible requests, use Authorization: Bearer YOUR_API_KEY. Avoid adding quotes, whitespace, or the word “Bearer” twice.
• Check environment loading: Print whether the variable exists, not the key itself. A common production bug is a missing secret after a deployment or container restart.
• Check the base URL: When using 59API with an OpenAI SDK, configure the client base URL as documented for https://api.59api.com; do not accidentally send a 59API key to the default OpenAI endpoint.
• Check model access: Confirm that the requested Claude or GPT model identifier is enabled and spelled exactly as required.

Pros of strict authorization: it limits accidental spend and key misuse. Cons: errors can be confusing when a valid key lacks access to only one model. Treat 401 as a credentials issue first and 403 as a permissions, plan, or model-selection issue.

429 Errors: Rate Limits, Quotas, and Retry Design

A 429 Too Many Requests does not always mean your code is sending requests too quickly. It can indicate requests-per-minute limits, tokens-per-minute limits, concurrent-request limits, or insufficient available balance. Read the response message and headers before changing anything.

• Retry only transient 429 responses with exponential backoff and jitter, such as 1, 2, 4, and 8 seconds plus random delay.
• Respect a Retry-After header when it is present.
• Limit concurrency with a queue; ten large simultaneous prompts can exhaust a token limit faster than one hundred short prompts.
• Reduce max output tokens and trim unnecessary chat history to lower token consumption.
• Do not retry balance, billing, or hard-quota failures indefinitely; alert the user or switch to an approved fallback model.

Pros of automatic retries: they smooth short traffic bursts. Cons: uncontrolled retries amplify load, duplicate non-idempotent work, and raise costs. Use idempotency keys where supported and store request state before retrying.

400 Errors: Invalid Requests, Context Limits, and Model Mismatches

A 400 Bad Request is usually deterministic: retrying it unchanged will fail again. Typical causes include invalid JSON, unsupported parameters, an invalid role sequence, an unavailable model name, or a prompt that exceeds the model context window.

First, log the serialized request body after secrets are removed. Validate JSON and compare your payload against the endpoint schema. Then count both input and requested output tokens. Context limits include conversation history, system instructions, tool definitions, retrieved documents, and the completion budget. If a request is too large, summarize older messages, retrieve fewer document chunks, shorten tool schemas, or lower the maximum output. Do not simply truncate the newest user instruction, because that can remove the task the model needs to answer.

Compatibility layers are useful because one OpenAI-style client can serve multiple models, but the downside is feature variation. A parameter accepted by one GPT endpoint may not apply to a Claude-compatible route, and model names are not interchangeable. Start with a minimal request, confirm it works, and add streaming, tools, structured output, or advanced sampling options one at a time.

Streaming, Tool Calls, and 5xx Failures

Streaming failures frequently come from proxies buffering Server-Sent Events, serverless function timeouts, or clients that assume every chunk contains text. Configure your proxy to preserve streaming, increase read timeouts, and handle finish events, usage events, and tool-call deltas separately. For tool calls, validate the model-produced arguments against a JSON schema before executing anything. Return tool errors to the model in a structured way instead of crashing the conversation.

A 500, 502, 503, or 504 can be temporary upstream instability, a gateway timeout, or an overloaded service. Retry these responses with bounded exponential backoff, but preserve the original request ID and avoid retrying expensive long generations more than a few times. If reliability matters, build a fallback policy: retry the same model once, then route eligible work to a lower-latency or lower-cost model while clearly monitoring quality changes.

A Practical Low-Cost Debugging Setup

Use structured logs, token metrics, request IDs, and a small test suite containing authentication, short completion, streaming, long-context, and tool-call cases. This makes provider changes safer and reveals whether failures are code defects or capacity constraints. For teams that want native-quality Claude and GPT access without maintaining multiple billing integrations, 59API is a practical low-cost, pay-as-you-go option, including a referral rebate. Sign up when you are ready to test your existing OpenAI SDK or Claude Code workflow against its compatible API endpoint.

Pricing · Docs