AI API Error Code Lookup — OpenAI, Claude & Gemini

Likely cause

• Malformed JSON body or a missing required field (e.g. model, messages, max_tokens).
• A parameter value out of range or of the wrong type.

Fix

Validate the request body against the Messages API schema. Check model name, required fields, and parameter types before resending.

Likely cause

• Missing, revoked, or mistyped x-api-key header.
• Using a key from the wrong organisation or workspace.

Fix

Confirm the x-api-key header carries a valid key from the Anthropic Console. Rotate the key if it may be exposed.

Likely cause

• The key lacks access to the requested model or feature.
• Workspace or organisation restrictions block the resource.

Fix

Use a key with access to the requested model, or request access for that model/feature in the Console.

Likely cause

• An unknown model id (typo or deprecated model).
• A wrong endpoint path or a message/batch id that does not exist.

Fix

Check the model id against the current models list and confirm the endpoint URL. Deprecated models return 404 once retired.

Likely cause

• Oversized prompt, document, or image payload in a single request.

Fix

Trim or chunk the input, downscale images, or use the Files API / prompt caching to avoid resending large context each call.

Likely cause

• Too many requests or tokens within the window for your usage tier.
• A burst of concurrent calls from multiple workers.

Fix

Wait for the time given in the retry-after response header, then retry. Smooth out bursts and consider a higher usage tier.

Likely cause

• A transient fault inside Anthropic's infrastructure.

Fix

Retry the same request with exponential backoff and jitter. If it persists, check status.anthropic.com.

Likely cause

• Transient server-side capacity pressure, often at peak hours.
• Not a bug in your code or request.

Fix

Retry the same request with exponential backoff + jitter and reduce concurrency. Avoid hammering immediately — it worsens the overload.

Likely cause

• Missing or invalid parameters (model, messages, etc.).
• Context length exceeded or an unsupported parameter for the chosen model.

Fix

Read the message field — it names the offending parameter. Fix it and resend. For context-length errors, shorten the prompt or raise the limit.

Likely cause

• Incorrect or expired API key.
• Missing Authorization header, or not a member of the billing organisation.

Fix

Use a valid key from the OpenAI dashboard and send it as `Authorization: Bearer <key>`. Set the correct OpenAI-Organization header if you belong to several.

Likely cause

• The request originates from a region OpenAI does not serve.
• A VPN or proxy egress in an unsupported location.

Fix

Access the API from a supported region. Check OpenAI's supported-countries list; disable any VPN that routes through an unsupported location.

Likely cause

• A typo or deprecated model name.
• Your account/tier has no access to that model yet.

Fix

Call the /v1/models endpoint to list models you can use, then correct the model id. Some models require tier or access approval.

Likely cause

• Requests-per-minute or tokens-per-minute limit exceeded.
• Spiky concurrency without client-side throttling.

Fix

Back off and retry with exponential backoff + jitter. Throttle client-side, batch where possible, and request a higher rate limit if you consistently hit it.

Likely cause

• No remaining prepaid credits, or the monthly hard limit was reached.
• An expired free trial.

Fix

Do not retry — it will keep failing. Add a payment method or credits in Billing and check your usage limits. This is a billing issue, not a rate issue.

Likely cause

• A transient fault on OpenAI's side.

Fix

Retry after a brief wait with exponential backoff. If it persists, check status.openai.com and contact support with the request id.

Likely cause

• High traffic / temporary capacity pressure on OpenAI's servers.

Fix

Retry with exponential backoff + jitter and lower your concurrency. Avoid immediate tight-loop retries.

Likely cause

• A typo or missing required field in the request body.
• An unsupported parameter or value for the chosen model.

Fix

Check the API reference for the correct request format and confirm the model supports the parameters you sent.

Likely cause

• Gemini API free tier not offered in your region.
• Billing not enabled on the Google Cloud project.

Fix

Enable billing on your Google Cloud project (a paid tier works in supported regions). Do not retry until billing/region is sorted.

Likely cause

• Wrong API key, or the key lacks access to the requested resource.
• A tuned model accessed without correct authentication.

Fix

Confirm the API key is correct and its access is set up. Check that any tuned model belongs to the authenticated project.

Likely cause

• An unknown model id or a file/resource that doesn't exist.
• Referencing an uploaded file that has expired.

Fix

Verify the model id and that any referenced files still exist (uploads expire). Re-upload files if needed.

Likely cause

• Sending requests faster than your quota allows.
• Free-tier quota limits reached.

Fix

Retry with exponential backoff and lower your request rate. Review your quotas and request an increase if you need more throughput.

Likely cause

• A transient fault in Gemini's infrastructure.
• Input context too long for the model to process.

Fix

Retry with exponential backoff. If it persists, reduce your input context or prompt size, or switch to a model with a larger context window.

Likely cause

• Temporary capacity pressure or maintenance on Google's side.

Fix

Retry with exponential backoff + jitter. If you need lower latency under load, consider switching to a less busy model temporarily.

Likely cause

• The prompt or context is too large to process in the allotted time.
• A client-side timeout that is set too low.

Fix

Increase your client timeout, or reduce the prompt size. Retry with exponential backoff once the request is smaller.