Errors and troubleshooting - APIONE AI

Save the HTTP status and redacted response body. Keep the X-Maxx-Request-ID response header when present. Errors may include error.message, error.type, error.code, and retryable, but interfaces do not all return the same structure or every field.

APIONE request logs error troubleshooting entry — Locate failure records in request details first, then troubleshoot using status, latency, model, and request ID.

Handle the status code

Status	Common meaning	First action
400	Invalid request, model, or parameter	Verify the model and remove optional fields
401	Missing, invalid, disabled, or expired key, or conflicting credentials	Check key status and use the required authentication method only
402	Insufficient balance	Check console balance and expected usage
403	Model access denied	Check the key’s available models and permissions
404	Missing endpoint, or a model not found during parameter lookup	Check the full URL; for parameter queries, verify the model ID and access
413	Request too large	Reduce input or message history
422	Estimated charge exceeds the per-request limit	Read the error and check input length and output limits
429	Key concurrency or upstream rate limit	Reduce concurrency and honor `Retry-After` when present
500 / 502 / 503	Temporary gateway or upstream issue	Retry within limits; contact support if it persists

This table follows APIONE’s error documentation. Read the actual response body. Model parameter queries may also return {"error":"model not found"}, so do not rely on error.code alone.

Diagnose in order

Confirm the HTTPS destination is api.apione.ai and check URL composition against API addresses.
Send a minimal text request with the same protocol. Check the model ID, key permissions, and balance.
Once it succeeds, restore optional parameters individually to find incompatible fields.
If cURL works but the application fails, check environment variables, the SDK’s actual URL, duplicate /v1, and proxy settings. See SDK setup.

Common identifiers

Identifier	Check
`model_not_supported`	Model availability and exact ID
`API_KEY_MODEL_DENIED`	The key’s permission to use the model
`unsupported_parameter`	The model’s supported parameters
`context_length_exceeded`	Input, history, and output limits

Retries

Correct configuration, permission, and balance errors first. Retry recoverable errors within a limit and account for SDK retries to avoid multiplying requests. A stream can fail after HTTP 200. Keep the output already received and its error rather than silently replaying the request, which can duplicate generation. See streaming.

Before contacting support

Include the time and time zone, protocol and endpoint, model ID, HTTP status, request ID, SDK or client version, redacted error body, and number of retries. Do not include full keys or sensitive business content. Use the report template.