Reference

API Error Codes — Messages API, OpenAI-compatible & Gemini

Every API error for GPT and Gemini models explained: Messages API 401 authentication_error, 402 balance, 429 rate_limit_error and 529 Overloaded; OpenAI 401 invalid_api_key, 402 insufficient_quota; Gemini 400 API_KEY_INVALID and 402 FAILED_PRECONDITION. Exact response text, cause and fix for each.

Every protocol keeps its official envelope. The Messages API (POST /v1/messages, Anthropic format) is the endpoint Claude Code and the Anthropic SDKs call; it serves GPT and Gemini models and returns every error in the Anthropic envelope, so you can branch on error.type:

{"type":"error","error":{"type":"authentication_error","message":"Invalid or missing API key."}}

Match on the HTTP status and the branch field (Messages error.type, OpenAI error.code, Gemini error.status / ErrorInfo reason), never on the message string — messages are prose and can be reworded, while those fields are the contract. In the official SDKs this means catching the typed exception classes rather than inspecting text. This page is written the other way round only because the message is what you have in front of you when something breaks. HTTP 402 is prepaid balance on every endpoint; do not retry it as a 429.

The Messages API uses one error.type for every client-fault 400: invalid_request_error. Different 400s are different messages. HTTP 402 carries invalid_request_error too, so branch on the status. Temporary capacity refusals are 529 overloaded_error with Retry-After. Rows are grouped by HTTP status, then type.

Messages API (/v1/messages, Anthropic format) — all codes

Open a row for the exact response body and the fix. You do not need to scroll past the other errors.

400invalid_request_errorinvalid JSON in request bodyNo
HTTP 400
{"type":"error","error":{"type":"invalid_request_error","message":"Invalid JSON in request body."}}

Why it happens

  • The body is not valid JSON — a trailing comma, a single-quoted string, or a shell variable that expanded into an unescaped quote.
  • A body that is valid JSON but has no string model field fails with a sibling message: Missing or invalid required parameter: model.

How to fix it

  • Validate the body before sending. Most of these never reach the API in a working state.
  • In shell scripts, build the body with a heredoc or jq rather than string interpolation.

Other forms of the same failure

  • Missing or invalid required parameter: model.

Short link: https://apitoken.sale/e/invalid-request-body · This response text is specific to the apiToken.sale Messages API.

400invalid_request_errormaximum context length exceededNo
HTTP 400
{"type":"error","error":{"type":"invalid_request_error","message":"This model's maximum context length was exceeded."}}

Why it happens

  • The request exceeds the context window of the selected model. The window differs per model; each model page lists it.
  • An agent loop that appends every tool result to the history without ever pruning it.
  • Large files or documents pasted inline rather than summarised or split.

How to fix it

  • Count before sending: POST /v1/messages/count_tokens returns input_tokens for the same model and body without running the model.
  • Prune old tool results from the history, or compact the conversation (in Claude Code: /compact) so earlier turns are summarised instead of resent verbatim.
  • For long documents, pick a model with a larger window — the same key and endpoint serve every GPT and Gemini model.

Other forms of the same failure

  • {"error":{"message":"This model's maximum context length was exceeded.","type":"invalid_request_error","param":"input","code":"context_length_exceeded"}}
  • context_length_exceeded

Short link: https://apitoken.sale/e/prompt-too-long · This response text is specific to the apiToken.sale Messages API.

400invalid_request_errorthinking.budget_tokens below 1024No
HTTP 400
{"type":"error","error":{"type":"invalid_request_error","message":"Invalid value for parameter: thinking.budget_tokens must be at least 1024."}}

Why it happens

  • thinking.type is enabled with a budget_tokens below 1024. The endpoint maps a fixed budget onto the model's reasoning effort, and 1024 is the smallest budget it accepts.
  • A budget of 0, a negative number or a string fails with a sibling message: thinking.budget_tokens must be a positive integer.

How to fix it

  • Raise budget_tokens to 1024 or more, or switch to adaptive thinking and set the depth with output_config.effort (low, medium, high, xhigh, max — the levels the model advertises). Effort goes inside output_config, not at the top level.
  • Know the mapping: a budget below 4096 runs at low effort, below 16384 at medium, anything larger at high. Adaptive and disabled thinking use the model's default effort.

Current form

thinking={"type": "adaptive"},
output_config={"effort": "high"}

Other forms of the same failure

  • thinking.budget_tokens must be at least 1024
  • Invalid type for parameter: thinking.budget_tokens must be a positive integer.

Short link: https://apitoken.sale/e/thinking-budget-tokens · This response text is specific to the apiToken.sale Messages API.

400invalid_request_errortool_result without a matching tool_useNo
HTTP 400
{"type":"error","error":{"type":"invalid_request_error","message":"tool_result tool_use_id has no matching tool_use in this history (messages.2.content.0.tool_use_id)."}}

Why it happens

  • A tool_result block names a tool_use_id that no earlier assistant turn in the request contains. On google/* models the endpoint checks this pairing before the request leaves, because Gemini needs the function name of every result.
  • The history was trimmed or compacted, and the assistant turn with the tool_use was dropped while its tool_result was kept.
  • Only the text was appended to the history instead of the full response content, so the tool_use blocks were silently lost.
  • On openai/* models the endpoint does not run this check, so the same history can pass there and fail on a google/* model.

How to fix it

  • Append the entire response content to the history, not just the text.
  • When you trim history, drop each tool_use together with its tool_result — never one without the other.
  • On failure, still return a tool_result with is_error set — never omit it.

Other forms of the same failure

  • tool_result requires a non-empty tool_use_id
  • claude code tool_result error

Short link: https://apitoken.sale/e/tool-result-missing · This response text is specific to the apiToken.sale Messages API.

400invalid_request_errorStreaming required for long operationsNo
HTTP 400
{"type":"error","error":{"type":"invalid_request_error","message":"Streaming is strongly recommended for operations that may take longer than 10 minutes"}}

Why it happens

  • A non-streaming request was made with a max_tokens large enough that the response could exceed the request timeout.
  • The official Anthropic SDK raises this itself before the request leaves your machine, so it appears with any model id, including openai/* and google/* ones.
  • It shows up most in no-code and workflow tools, where the node sets a large max_tokens but does not expose a streaming toggle.

How to fix it

  • Stream the request and collect the final message from the stream helper.
  • If streaming is not available in your tool, lower max_tokens to something the timeout can accommodate — roughly 16K output tokens is a safe non-streaming ceiling.

Stream and take the final message

with client.messages.stream(model="openai/gpt-6.1-terra", max_tokens=64000, …) as stream:
    message = stream.get_final_message()

Other forms of the same failure

  • Streaming is required for operations that may take longer than 10 minutes

Short link: https://apitoken.sale/e/streaming-required · Same text as the official Anthropic Messages API, so existing error handling works unchanged.

401authentication_errorinvalid or missing API keyNo
HTTP 401
{"type":"error","error":{"type":"authentication_error","message":"Invalid or missing API key."}}

Why it happens

  • No key reached the endpoint: the environment variable is unset or empty in the shell that actually runs the process.
  • The key was revoked, or expired if it was issued with an expiry date.
  • The base URL still points at api.anthropic.com, so the key goes to a server that has never seen it. That server answers with its own text: invalid x-api-key.
  • The endpoint accepts the key in x-api-key (ANTHROPIC_API_KEY) or in Authorization: Bearer (ANTHROPIC_AUTH_TOKEN). When both are sent, one valid key is enough, so a 401 means that no key in the request is valid.

How to fix it

  • Print the first few characters of the variable inside the same process that fails. Most 401s are an environment or quoting problem rather than a bad key.
  • Set the base URL to https://router.apitoken.sale and keep one credential variable, so a stale key from another provider cannot confuse the setup.
  • Confirm the key is active in your dashboard.

Check what is actually being sent

# Is the variable set in THIS shell?
echo "${ANTHROPIC_AUTH_TOKEN:0:12}…"
# Which Anthropic client variables are set?
env | grep -E 'ANTHROPIC_(API_KEY|AUTH_TOKEN|BASE_URL)'

curl https://router.apitoken.sale/v1/models \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

Other forms of the same failure

  • {"type":"error","error":{"type":"authentication_error","message":"invalid x-api-key"}}
  • anthropic.AuthenticationError
  • claude code 401 custom ANTHROPIC_BASE_URL

Short link: https://apitoken.sale/e/invalid-api-key · This response text is specific to the apiToken.sale Messages API.

402invalid_request_erroraccount balance is insufficientNo
HTTP 402
{"type":"error","error":{"type":"invalid_request_error","message":"Your account balance is insufficient for this request."}}

Why it happens

  • The prepaid balance does not cover the request just submitted.
  • The key carries its own spending limit and has reached it, even though the account still has balance. The response is the same.
  • The status is HTTP 402 and error.type is invalid_request_error. On google/* models the text reads The account balance is insufficient for this request. It is not a 429 — SDKs retry 429.

How to fix it

  • Top up the balance, or raise the spending limit on that key.
  • Confirm the live balance after the payment is credited. A pending top-up is not spendable yet.
  • Read the live balance with the same key you use for inference. Branch on HTTP 402, not on error.type or the message string.

Check the balance for a key

curl https://router.apitoken.sale/balance \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

Other forms of the same failure

  • {"type":"error","error":{"type":"invalid_request_error","message":"The account balance is insufficient for this request."}}
  • api key spending limit reached
  • claude code api error 402

Short link: https://apitoken.sale/e/insufficient-balance · This response text is specific to the apiToken.sale Messages API.

404not_found_errormodel or endpoint not foundNo
HTTP 404
{"type":"error","error":{"type":"not_found_error","message":"The model `gpt-9.9` does not exist or you do not have access to it."}}

Why it happens

  • A model id that the catalog does not list: a typo, a retired id, or an id copied from another provider's naming.
  • A namespaced id with the wrong prefix. GPT models are openai/<id> and Gemini models google/<id>, for example openai/gpt-6.1-terra or google/gemini-3.8-flash.
  • A base URL that already ends in /v1, so the SDK produced /v1/v1/messages. That path answers a different 404: The requested endpoint is not supported.

How to fix it

  • Set the base URL to the origin only (https://router.apitoken.sale) and let the SDK append /v1 itself.
  • List the models the key can actually reach instead of guessing an id.
  • Copy the id character for character from that list or the model page — gpt-6.1-terra, not gpt6.1-terra or gpt-6.1.terra.

List the models this key can use

curl https://router.apitoken.sale/v1/models \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

Other forms of the same failure

  • {"error":{"message":"The requested endpoint is not supported.","type":"invalid_request_error","code":"unsupported_endpoint"}}
  • anthropic.NotFoundError

Short link: https://apitoken.sale/e/not-found · This response text is specific to the apiToken.sale Messages API.

413request_too_largerequest body too largeNo
HTTP 413
{"type":"error","error":{"type":"request_too_large","message":"Request body exceeds the 300 MiB limit."}}

Why it happens

  • The serialized body is larger than 300 MiB. Base64-encoded images and PDFs are the usual reason.
  • Base64 inflates binary data by roughly a third, so a file that looks safe on disk can be over the limit on the wire.
  • A long agent history resends every earlier attachment on every turn, so the body grows even when each new message is small.

How to fix it

  • Resize or recompress images before encoding — most vision tasks do not need the original resolution.
  • Send an image as a url source instead of base64 when your client allows it; the endpoint fetches it, so the bytes do not travel in your request.
  • Trim the message history instead of replaying every turn verbatim.

Other forms of the same failure

  • request_too_large

Short link: https://apitoken.sale/e/request-too-large · This response text is specific to the apiToken.sale Messages API.

429rate_limit_errorrate limit reachedYes, back off
HTTP 429
{"type":"error","error":{"type":"rate_limit_error","message":"Rate limit reached. Please retry shortly."}}

Why it happens

  • The account's rate or concurrency ceiling was exceeded. A burst with no concurrency cap — a parallel map over a large list, or several agent sessions on one key — is the usual cause.
  • Retries piling on top of the requests that caused the first 429, which enlarges the burst instead of draining it.
  • On google/* models the text comes from the Gemini side — Resource has been exhausted. Please retry later. — while the status and error.type stay the same.

How to fix it

  • Honour the Retry-After header rather than guessing an interval — the response carries one.
  • The official Anthropic SDKs already retry 429 and 5xx with exponential backoff (twice by default) — raise max_retries instead of hand-rolling a loop.
  • Cap concurrency at the call site. A semaphore fixes more 429s than any retry policy.
  • Do not confuse this with HTTP 402 — that is empty prepaid balance. 429 is retryable throughput. Top up for 402; honour Retry-After for 429.

Let the SDK back off for you

import anthropic

client = anthropic.Anthropic(
    base_url="https://router.apitoken.sale",
    max_retries=5,  # retries 429 and 5xx with backoff
)

Other forms of the same failure

  • {"type":"error","error":{"type":"rate_limit_error","message":"Resource has been exhausted. Please retry later."}}
  • anthropic.RateLimitError
  • claude code api error 429

Short link: https://apitoken.sale/e/rate-limit · This response text is specific to the apiToken.sale Messages API.

500api_errorinternal server errorYes, back off
HTTP 500
{"type":"error","error":{"type":"api_error","message":"Internal server error"}}

Why it happens

  • An unexpected failure while processing the request. Nothing in your payload caused it.

How to fix it

  • Retry with exponential backoff — the SDKs do this for 5xx automatically.
  • If it persists for one request while others succeed, capture the request id and send it to support.

Other forms of the same failure

  • anthropic.InternalServerError

Short link: https://apitoken.sale/e/api-error · Same text as the official Anthropic Messages API, so existing error handling works unchanged.

529overloaded_errorOverloadedYes, back off
HTTP 529
{"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}

Why it happens

  • Upstream capacity for the requested GPT or Gemini model is temporarily saturated. 529 describes the service, not your request.
  • The endpoint reports every temporary capacity refusal as 529 overloaded_error, the status Anthropic clients already retry, and keeps the Retry-After header.
  • It clusters during incidents: the same request typically succeeds minutes later with no change.

How to fix it

  • Retry with exponential backoff and jitter. Never in a tight loop — that is what produced the pile-up.
  • Note the status is 529, not 503. Some HTTP clients and proxies only treat a hardcoded set of codes as retryable and omit 529, so the retry you think you have may not fire.
  • For latency-sensitive paths, fall back to another GPT or Gemini model: capacity is per model, so a different one is often free.

Other forms of the same failure

  • API Error: 529 {"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}
  • claude code 529 overloaded

Short link: https://apitoken.sale/e/overloaded · Same text as the official Anthropic Messages API, so existing error handling works unchanged.

OpenAI lanes — all codes

The OpenAI lanes return the OpenAI error envelope instead — branch on error.code and the HTTP status. A rejected feature returns 400 with code documented_limitation or unsupported_parameter, a named param, and a workaround in the message. These are the exact responses of router.apitoken.sale/v1:

{"error":{"message":"Incorrect API key provided.","type":"invalid_request_error","param":null,"code":"invalid_api_key"}}

Open a row for the exact response body and the fix. You do not need to scroll past the other errors.

400invalid_request_error / documented_limitationdocumented limitation (hosted tool)No
HTTP 400
{"error":{"message":"tools.0.type cannot be honoured on this endpoint. The official OpenAI API accepts it; omit this 'hosted_shell' tool or use a client-side custom tool.","type":"invalid_request_error","param":"tools.0.type","code":"documented_limitation"}}

Why it happens

  • The official OpenAI API accepts this field or tool type. This endpoint cannot honour it, so the request is refused before dispatch — never a silent 200 that dropped the field.
  • The same class covers hosted_shell, code_interpreter, apply_patch, skills, file_search, computer, mcp, prompt_cache_retention, reasoning.mode, store / previous_response_id / item_reference on a non-openai/* model.
  • error.type stays invalid_request_error. Branch on error.code documented_limitation and error.param.

How to fix it

  • Omit the named field, or follow the workaround in the message (client-side custom tool, PNG data URL, openai/* model for stored responses).
  • Do not retry the identical body. Switch to the model's native lane only when that lane actually honours the field.

Other forms of the same failure

  • store cannot be honoured on this endpoint. The official OpenAI API accepts it; omit 'store' or use an openai/* model.
  • prompt_cache_retention cannot be honoured on this endpoint. The official OpenAI API accepts it; omit 'prompt_cache_retention'.
  • reasoning.mode cannot be honoured on this endpoint. The official OpenAI API accepts it; omit 'reasoning.mode'.
  • documented_limitation OpenAI

Short link: https://apitoken.sale/e/openai-documented-limitation · Returned by the OpenAI lanes of the unified endpoint (router.apitoken.sale/v1).

400invalid_request_error / unsupported_parameterunsupported parameterNo
HTTP 400
{"error":{"message":"Unsupported parameter: 'n' is not supported with this endpoint.","type":"invalid_request_error","param":"n","code":"unsupported_parameter"}}

Why it happens

  • This HTTP path never accepts the named field. Chat n other than 1 on a google/* model is the usual case.
  • Distinct from documented_limitation: unsupported_parameter is the wrong shape for this endpoint; documented_limitation is a gap versus the official API of the capacity provider.
  • Default or omitted or JSON null is not a refusal. Only a present non-null value that cannot be honoured returns 400.

How to fix it

  • Omit the named parameter, or send its default value (n=1).
  • If you need the official behaviour, call the native lane that actually accepts the field.

Other forms of the same failure

  • 400 unsupported_parameter

Short link: https://apitoken.sale/e/openai-unsupported-parameter · Returned by the OpenAI lanes of the unified endpoint (router.apitoken.sale/v1).

401invalid_request_error / invalid_api_keyIncorrect API key providedNo
HTTP 401
{"error":{"message":"Incorrect API key provided.","type":"invalid_request_error","param":null,"code":"invalid_api_key"}}

Why it happens

  • The key was sent in the x-api-key header. The OpenAI lanes authenticate with Authorization: Bearer — x-api-key belongs to the Messages API (/v1/messages).
  • The Authorization header is missing the Bearer prefix, or the environment variable it was built from is empty in the shell that runs the process.
  • The key was revoked, or expired if it was issued with an expiry date.
  • The key is valid but the base URL points at another provider, so the key reaches a server that has never seen it. Use router.apitoken.sale/v1.

How to fix it

  • Send the same sk-pool key as Authorization: Bearer sk-pool-… to https://router.apitoken.sale/v1.
  • With the official OpenAI SDK, set api_key (or OPENAI_API_KEY) and base_url — the SDK adds the Bearer header for you.
  • Confirm the key is active in your dashboard and that the host is the OpenAI lane of the unified endpoint.

Reproduce outside your tool

curl https://router.apitoken.sale/v1/models \
  -H "Authorization: Bearer $APITOKEN_API_KEY"

Other forms of the same failure

  • {"error":{"message":"Incorrect API key provided.","type":"invalid_request_error","param":null,"code":"invalid_api_key"}}
  • openai.AuthenticationError
  • codex stream error: unexpected status 401

Short link: https://apitoken.sale/e/openai-invalid-api-key · Returned by the OpenAI lanes of the unified endpoint (router.apitoken.sale/v1).

402insufficient_quota / insufficient_quotaaccount balance is insufficientNo
HTTP 402
{"error":{"message":"Your account balance is insufficient for this request.","type":"insufficient_quota","param":null,"code":"insufficient_quota"}}

Why it happens

  • The prepaid balance shared by every lane of the unified endpoint is too low to cover the request.
  • Spend on one lane empties the same balance for the others.
  • HTTP status is 402, not 429. Official OpenAI Platform puts money on 429 insufficient_quota; this product does not, because OpenAI SDKs retry 429. type and code stay insufficient_quota so you can still branch on the field.

How to fix it

  • Top up any whole-dollar amount and retry after the payment is credited. Backoff alone never resolves a 402.
  • Confirm the live balance with the same key before retrying.
  • Treat 429 as retryable capacity. Treat 402 insufficient_quota as empty prepaid balance.

Other forms of the same failure

  • openai insufficient_quota
  • codex 402 insufficient balance

Short link: https://apitoken.sale/e/openai-insufficient-quota · Returned by the OpenAI lanes of the unified endpoint (router.apitoken.sale/v1).

404invalid_request_error / model_not_foundmodel does not existNo
HTTP 404
{"error":{"message":"The model \"gpt-9.9\" does not exist or you do not have access to it.","type":"invalid_request_error","param":null,"code":"model_not_found"}}

Why it happens

  • The model ID is misspelled, or it needs the namespaced form: on the shared lanes the catalog publishes openai/gpt-* and google/gemini-*, and a bare native ID fails once it becomes ambiguous.
  • The model is not in the currently enabled catalog — the served set changes as models are admitted.

How to fix it

  • List the models your key can actually use: GET https://router.apitoken.sale/v1/models with Authorization: Bearer.
  • Check the ID character for character — gpt-5.6-sol, not gpt5.6 or gpt-5.6.sol. gpt-5.6 is a valid alias of gpt-5.6-sol.

Discover the enabled models

curl https://router.apitoken.sale/v1/models \
  -H "Authorization: Bearer $APITOKEN_API_KEY"

Other forms of the same failure

  • openai model_not_found
  • codex stream error: unexpected status 404
  • The model does not exist or you do not have access to it

Short link: https://apitoken.sale/e/openai-model-not-found · Returned by the OpenAI lanes of the unified endpoint (router.apitoken.sale/v1).

429rate_limit_error / rate_limit_exceededrate limit reachedYes, back off
HTTP 429
{"error":{"message":"Rate limit reached. Please retry shortly.","type":"rate_limit_error","param":null,"code":"rate_limit_exceeded"}}

Why it happens

  • The account's concurrency or rate ceiling was exceeded — a parallel burst with no cap is the usual cause.
  • Retries piling on top of the requests that caused the first 429 enlarge the burst instead of draining it.

How to fix it

  • Honor the Retry-After header — the response carries one.
  • Retry with capped exponential backoff and jitter, and cap concurrency at the call site.

Other forms of the same failure

  • openai rate_limit_error
  • codex stream error: unexpected status 429

Short link: https://apitoken.sale/e/openai-rate-limit · Returned by the OpenAI lanes of the unified endpoint (router.apitoken.sale/v1).

503server_error / service_unavailablemodel temporarily unavailableYes, back off
HTTP 503
{"error":{"message":"The requested model is temporarily unavailable. Please retry.","type":"server_error","param":null,"code":"service_unavailable"}}

Why it happens

  • Upstream capacity for the requested model is temporarily saturated. 503 describes the service, not your request.
  • It clusters during incidents: the same request typically succeeds minutes later with no change.

How to fix it

  • Retry with exponential backoff and jitter — the response carries a Retry-After hint.
  • For latency-sensitive paths, fall back to another enabled model tier, which is generally less contended.

Other forms of the same failure

  • openai service_unavailable server_error

Short link: https://apitoken.sale/e/openai-service-unavailable · Returned by the OpenAI lanes of the unified endpoint (router.apitoken.sale/v1).

Gemini lane — all codes

The native Gemini lane returns the Google error envelope — branch on error.status and ErrorInfo reason. Invalid customer keys are 400 INVALID_ARGUMENT / API_KEY_INVALID. Prepaid money is 402 FAILED_PRECONDITION. A field the official Gemini API accepts and this endpoint cannot honour is 400 INVALID_ARGUMENT with a stable *_UNSUPPORTED reason:

{"error":{"code":400,"message":"API key not valid. Please pass a valid API key.","status":"INVALID_ARGUMENT","details":[{"@type":"type.googleapis.com/google.rpc.ErrorInfo","reason":"API_KEY_INVALID","domain":"googleapis.com"}]}}

Open a row for the exact response body and the fix. You do not need to scroll past the other errors.

400INVALID_ARGUMENT / API_KEY_INVALIDAPI_KEY_INVALIDNo
HTTP 400
{"error":{"code":400,"message":"API key not valid. Please pass a valid API key.","status":"INVALID_ARGUMENT","details":[{"@type":"type.googleapis.com/google.rpc.ErrorInfo","reason":"API_KEY_INVALID","domain":"googleapis.com","metadata":{"service":"generativelanguage.googleapis.com"}}]}}

Why it happens

  • The native Gemini lane answers 400 INVALID_ARGUMENT with ErrorInfo reason API_KEY_INVALID — the official Google API does the same. Other lanes answer 401.
  • The x-goog-api-key header is missing, empty, mistyped, or carries a revoked key.
  • x-api-key or Authorization: Bearer was sent instead. Those headers belong to the Messages API and the OpenAI lanes.

How to fix it

  • Send an active sk-pool key in x-goog-api-key. Treat this 400 exactly like a 401: do not retry the same key.
  • If the key was revoked, create a replacement in the dashboard.

Other forms of the same failure

  • API_KEY_INVALID
  • API key not valid. Please pass a valid API key.

Short link: https://apitoken.sale/e/gemini-invalid-api-key · Returned by the native Gemini lane (router.apitoken.sale/v1beta and gemini.api.apitoken.sale).

400INVALID_ARGUMENT / FILE_URI_UNSUPPORTEDFILE_URI_UNSUPPORTEDNo
HTTP 400
{"error":{"code":400,"message":"fileData cannot be honoured on this endpoint. The official Gemini API accepts it; send the file as inlineData with mimeType and base64 data.","status":"INVALID_ARGUMENT","details":[{"@type":"type.googleapis.com/google.rpc.ErrorInfo","reason":"FILE_URI_UNSUPPORTED","domain":"googleapis.com","metadata":{"service":"generativelanguage.googleapis.com","param":"fileData"}}]}}

Why it happens

  • The official Gemini API accepts fileData / file_uri. This endpoint cannot honour a Google-project Files API reference on synchronous generateContent, so it fails closed with a stable ErrorInfo reason.
  • The same class covers cachedContent (CACHED_CONTENT_UNSUPPORTED), explicit serviceTier, explicit store logging controls, and audio on a model this gateway does not serve audio for.

How to fix it

  • Send the file inline as inlineData with its mimeType and base64 data.
  • Do not retry the identical body.

Other forms of the same failure

  • cachedContent cannot be honoured on this endpoint. The official Gemini API accepts it; omit 'cachedContent' or send the content inline.
  • CACHED_CONTENT_UNSUPPORTED
  • FILE_URI_UNSUPPORTED

Short link: https://apitoken.sale/e/gemini-file-uri-unsupported · Returned by the native Gemini lane (router.apitoken.sale/v1beta and gemini.api.apitoken.sale).

402FAILED_PRECONDITIONFAILED_PRECONDITION (prepaid balance)No
HTTP 402
{"error":{"code":402,"message":"The account balance is insufficient for this request.","status":"FAILED_PRECONDITION"}}

Why it happens

  • The shared prepaid balance cannot cover the request. Gemini has no money 402 on the official API; this gateway still sends HTTP 402 so clients do not retry it as capacity.
  • error.status is FAILED_PRECONDITION. It is not RESOURCE_EXHAUSTED and it is not 429.

How to fix it

  • Top up any whole-dollar amount and retry after the payment is credited.
  • Do not treat 402 as a rate limit. Backoff never restores an empty balance.

Other forms of the same failure

  • The account balance is insufficient for this request.
  • gemini 402 FAILED_PRECONDITION

Short link: https://apitoken.sale/e/gemini-insufficient-balance · Returned by the native Gemini lane (router.apitoken.sale/v1beta and gemini.api.apitoken.sale).

Still stuck?

If a request fails in a way this page does not cover, send us the endpoint, the masked key id, the HTTP status and the response body. Never send the full key.

apiToken.sale serves GPT and Gemini models through the Messages API (Anthropic format), OpenAI Responses and Chat Completions, and the native Gemini API on one unified router endpoint, so every error whose text matches the official API behaves exactly as it does against the official endpoints. See also how to run Claude Code on GPT and Gemini models through this endpoint.