← Voltar aos guias

LLM API Errors: A 2026 Fix-It Guide

LLM APIs fail for familiar reasons: an invalid request body, an expired key, a rate limit, an incorrect model name, or a timeout between your application and the provider. The fastest way to recover is to classify the error first, then apply a targeted fix instead of repeatedly retrying the same request.

This 2026 guide covers the most common LLM API errors and practical steps for diagnosing them across OpenAI-compatible clients, Claude Code, Codex, Gemini CLI, and other SDK-based integrations.

400: Invalid request

A 400 error usually means the server understood your request but rejected its contents. Common causes include a missing required field, an unsupported parameter, malformed JSON, an invalid message role, or a tool definition that does not match the expected schema.

• Log the HTTP response body, not just the status code. It often identifies the exact field that failed validation.
• Confirm that messages contain valid roles and non-empty content where required.
• Remove optional parameters one at a time, especially provider-specific sampling, tool, and response-format settings.
• Validate JSON before sending it and make sure your SDK is not serializing a nested object as a string.

When switching models, review supported features. A parameter accepted by one model may be rejected by another, even when both use an OpenAI-compatible API.

401 or 403: Authentication and access

A 401 response normally indicates a missing, malformed, expired, or incorrectly loaded API key. Check that the key is present in the process that actually makes the request, particularly when running inside Docker, CI, a system service, or Claude Code.

A 403 can indicate that the key is valid but lacks permission for the requested model, endpoint, organization, or account balance. Verify the model identifier exactly, check account status, and inspect whether a proxy or gateway is replacing your authorization header. Never print full API keys in logs; record only a short fingerprint or the final four characters.

404: Wrong endpoint or model

404 errors are often configuration errors rather than unavailable models. Confirm the base URL, path, API version, and model name. For 59API, the API base URL is https://api.59api.com. When using an OpenAI SDK, set its base URL explicitly and avoid accidentally appending a second version path that the SDK already supplies.

Model names are exact identifiers. For example, use Claude Sonnet 5.5 or Gemini 3.1 Pro exactly as provided by the service, including punctuation and capitalization. Do not silently substitute an older model name when migrating a configuration.

429: Rate limits and depleted credits

A 429 response means the request cannot be accepted at that moment. It may reflect requests per minute, tokens per minute, concurrent-request limits, or insufficient prepaid balance.

• Honor the Retry-After header when it is provided.
• Use exponential backoff with jitter, such as 1, 2, 4, and 8 seconds plus a random delay.
• Cap retries and place a maximum deadline on each request.
• Reduce concurrency and queue work instead of launching unlimited parallel calls.
• Track input and output tokens so you can distinguish throttling from budget exhaustion.

Do not retry every 429 forever. Return a useful fallback or queue status to the user when the service remains unavailable.

408, 5xx, and network timeouts

Timeouts can occur during connection setup, model generation, or response streaming. Set separate connect and read timeouts, keep requests idempotent where possible, and retry transient 408, 502, 503, and 504 responses with bounded backoff. A retry after a partial streamed response can duplicate content, so assign a request ID and make downstream writes deduplicated.

For 500-level errors, capture the provider request ID, timestamp, model, latency, and a redacted request summary. This gives support enough information to investigate without exposing prompts or credentials.

Context and output failures

Requests can fail when the prompt, conversation history, tool schemas, and requested output exceed the model context window. Count tokens before sending, truncate or summarize old turns, and reserve space for the expected completion. Also set a practical maximum output length so a single response cannot consume an unexpected budget.

If your application expects JSON, validate the returned content before parsing it. Use a schema-capable response mode when the selected model supports it, but still handle truncated or refusal responses gracefully.

A lower-cost way to test fixes

Repeated debugging can become expensive when every failed experiment uses a high-priced provider route. 59API offers pay-as-you-go access to native official-quality models without a downgrade, including economical options such as DeepSeek V4 Flash and Gemini 3.8 Flash, while remaining compatible with Claude Code, Codex, Gemini CLI, and OpenAI SDKs. Developers can use the same base URL, add structured logging, and test retries and fallback behavior without committing to a large subscription.

After confirming your integration, sign up for 59API and compare its low-cost usage for your workload. A referral rebate is also available, which can reduce the effective cost of ongoing development and testing.

Preços · Docs