AI API Troubleshooting

This page lists common LLMPool AI API errors, their likely causes, and recommended actions. First confirm that the request uses the correct protocol:

OpenAI-compatible Base URL: https://api.benpay.ai/openai/v1
Anthropic-compatible Base URL: https://api.benpay.ai/anthropic/v1

See Error Responses for the response fields.

How to read the tables: Use the HTTP status to identify the broad error category, then use OpenAI error.code or Anthropic error.type to select the specific handling. Do not use message text for programmatic decisions.

Recommended diagnostic order

Record the HTTP status, request path, and request identifiers from response headers. Do not record credentials or the complete request body.
Even for a non-2xx status, first determine whether the body is a structurally valid business object for the endpoint, such as a Response with status: "failed"; otherwise parse the protocol error envelope.
For OpenAI, diagnose with the HTTP status and error.code. For Anthropic, use the HTTP status and error.type. Treat message as human-readable text only.
Use the tables below to decide whether to correct the request, contact platform support, or retry a limited number of times. Before retrying, confirm that the operation is safe to replay.

Authentication and access

OpenAI `error.code`	Anthropic `error.type`	HTTP	Auto retry	Cause	Resolution
`invalid_api_key`	`authentication_error`	`401`	No	The API key is missing, malformed, invalid, expired, disabled, unbound, or belongs to an unavailable account	Verify the header and Base URL; check the key in API Keys and create a new key if necessary
`ip_not_allowed`	`authentication_error` with `error.code=ip_not_allowed`	`403`	No	The source IP is outside the API key allowlist, or a proxy did not pass the expected client IP	Check the API key IP allowlist, outbound IP, and reverse-proxy `X-Forwarded-For` / `X-Real-IP` configuration

For OpenAI, use:

Authorization: Bearer YOUR_API_KEY

For Anthropic, prefer:

x-api-key: YOUR_API_KEY

Anthropic also accepts Authorization: Bearer YOUR_API_KEY. When both headers are present, LLMPool prefers x-api-key.

Balance and billing

OpenAI `error.code`	Anthropic `error.type`	HTTP	Auto retry	Cause	Resolution
`insufficient_wallets`	`invalid_request_error`, no distinct value	`402`	No	Available wallet and subscription balance is insufficient	Fund the account or contact the organization owner, then submit the request again
`meter_price_rules_error`	Not applicable	`400` or `500`	No	Missing or incomplete meter rules return `400`; failure to load the rules returns `500`	Select another available model or contact platform support; retrying unchanged will not fix it

Requests and parameters

OpenAI `error.code`	Anthropic `error.type`	HTTP	Auto retry	Cause	Resolution
`invalid_request`	`invalid_request_error`	`400`	No	JSON, Content-Type, or framework parsing failed	Check the JSON, `Content-Type`, field types, and required fields
`invalid_request_error`	`invalid_request_error`	`400` or `422`	No	The upstream rejected a parameter or field combination	Check the parameters and content types supported by the target model
`missing_model`	`invalid_request_error`, no distinct value	`400`	No	The request body has no `model` or the model value is empty	Use a Product ID shown on the Models page
`context_length_exceeded`	`invalid_request_error`, no distinct value	`400`	No	Input plus expected output exceeds the model context window	Shorten conversation history, attachments, or maximum output tokens, or select a model with a larger context window
`conversion_error`	Not applicable	`400`	No	A Chat Completions request cannot be converted into the target Responses request	Simplify the input and remove unsupported Responses fields or content types
`request_too_large`	`request_too_large`	`413`	No	The complete HTTP request body exceeds the service limit	Reduce text, image, or file size; do not embed large files directly in the request
`method_not_allowed`	`invalid_request_error`	`405`	No	The route exists but the HTTP method is wrong	Use the documented GET, POST, or DELETE method
`not_found`	`not_found_error`	`404`	No	The API route or requested general resource does not exist	Check the Base URL, versioned path, and resource ID

Upstream parameter failures are replaced with a safe, normalized message. Clients should not depend on an individual provider's original error text.

Models and routing

OpenAI `error.code`	Anthropic `error.type`	HTTP	Auto retry	Cause	Resolution
`invalid_model`	`invalid_request_error`, no distinct value	`400`	No	The model identifier is empty or malformed	Copy the Product ID from Models; do not use an upstream model fullname
`model_not_found`	`not_found_error`	`404`	No	The Product cannot be found	Check the spelling and confirm that the model is still shown on Models
`model_not_supported`	`invalid_request_error`, no distinct value	`400`	No	The Product does not support the selected protocol or feature, such as images, audio, Batch, or Responses	Select a model that supports the operation, or use an API supported by the model
`service_unavailable`	`overloaded_error`	OpenAI `503` / Anthropic `529`	Yes	The Product exists but has no currently available matching model or capacity	Retry with backoff or select another available model from Models

Appearing in the model catalog means a model can be discovered, but does not guarantee current inference capacity. Inference also requires an available Product and a matching online model.

Rate limits

OpenAI `error.code`	Anthropic `error.type`	HTTP	Auto retry	Cause	Resolution
`rate_limit_exceeded`	`rate_limit_error`	`429`	Yes	A client IP, API key, platform, or upstream request limit was reached	Honor `Retry-After` when present, use exponential backoff, and reduce concurrency
`rate_limited`	`rate_limit_error`	`429`	Yes	Every candidate upstream for the model is currently rate limited	Retry with backoff or change models; do not immediately replay the request concurrently

A reasonable backoff can start around 1s, double between attempts, and add random jitter. Always set a maximum attempt count and overall deadline.

Upstream services

OpenAI `error.code`	Anthropic `error.type`	HTTP	Auto retry	Cause	Resolution
`upstream_configuration_error`	`api_error`	OpenAI `502` / Anthropic `500`	No	The upstream rejected its credential, the model mapping is wrong, or the platform upstream configuration is invalid	Contact platform support; repeatedly changing your own API key will not help
`upstream_unavailable`	`api_error`	`502`	Yes	The upstream connection failed or the service is temporarily unavailable	Retry with backoff, change models if necessary, and contact support if it persists
`upstream_timeout`	`api_error`	`504`	Yes	The upstream did not respond before the timeout	Retry with backoff; for long inputs, consider shortening the context or expected output
Not applicable	`overloaded_error`	`529`	Yes	An Anthropic-compatible upstream is overloaded	Retry with backoff or select another model

LLMPool may try multiple upstream candidates. The final error is selected by failure class, so do not infer which provider was used from the message text.

Internal service errors

OpenAI `error.code`	Anthropic `error.type`	HTTP	Auto retry	Cause	Resolution
`internal_error`	`api_error`	`500`	Limited	A database, mapping, decryption, or other internal operation failed; Anthropic `api_error` can also be an upstream configuration problem	Retry a limited number of times after a delay, then stop and contact support
`file_service_error`	Not applicable	`500`	Limited	Internal image or attachment processing failed	Verify the attachment format and size, retry, and contact support if it persists
`response_conversion_error`	Not applicable	`500`	Limited	A Chat Completions upstream response could not be converted into a Responses object	Retry a limited number of times or change models, then contact support if it persists

Internal errors intentionally hide implementation details. Clients should not expect database, upstream address, or configuration information in the message.

Interrupted streams

After a stream starts, the HTTP status may remain 200 even when a later stream_error or Anthropic event: error is received.

Recommended handling:

End the current stream immediately and do not treat partial output as complete.
Record the structured error and local request time without logging the complete API key or sensitive request body.
Submit a new request with backoff only after confirming that retry is safe.
Change models and contact support if interruptions continue.

See Error Responses for the streaming event structures.

Common scenarios

Every request returns 401

Confirm that the request is sent to the LLMPool OpenAI or Anthropic Base URL, not the Dashboard URL.
Do not use an Admin Token or Tenant Access Token as an AI API key.
Copy the key again and check whitespace and header syntax.
Check whether the key is expired or disabled in the Dashboard.

The model returns 404

Copy the model name from Models.
Use a Product ID, not an internal provider model fullname.
Confirm that the protocol and operation match the model capabilities.

Requests frequently return 429

Reduce concurrency and requests per second.
Coordinate retries across application instances instead of retrying immediately from every instance.
Honor Retry-After and add random jitter.
Select another available model when only one model remains limited.

Requests frequently return 5xx or 529

First use a limited number of backoff retries and try another model.
Record the time, protocol, path, HTTP status, structured error type/code, and model Product ID.
Contact support when the issue persists or affects multiple models.

Contacting support

Provide:

Time of occurrence and time zone
OpenAI or Anthropic protocol
Request path and HTTP method
HTTP status, error.type, and error.code when present
Model Product ID
Whether the request was streaming and whether the issue is reproducible
Request identifiers from response headers when present

Do not provide complete API keys, request bodies, GraphQL documents or variables, file contents, or full URLs containing query parameters.