> ## Documentation Index
> Fetch the complete documentation index at: https://apione.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and troubleshooting

> Use status codes, error details, and request IDs to diagnose failures.

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](https://mintcdn.com/apione/pAFvFGkbmcRZirTZ/images/ui/request-logs.png?fit=max\&auto=format\&n=pAFvFGkbmcRZirTZ\&q=85\&s=093db383e228008dc3c42cb6a7849d28)

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](https://apione.ai/en/api-docs/docs/errors). 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

1. Confirm the HTTPS destination is `api.apione.ai` and check URL composition against [API addresses](https://apione.ai/docs/en/api/overview.md).
2. Send a minimal text request with the same protocol. Check the [model ID](https://apione.ai/docs/en/models/catalog.md), key permissions, and balance.
3. Once it succeeds, restore optional parameters individually to find incompatible fields.
4. If cURL works but the application fails, check environment variables, the SDK's actual URL, duplicate `/v1`, and proxy settings. See [SDK setup](https://apione.ai/docs/en/guides/sdks.md).

## 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](https://apione.ai/docs/en/models/streaming.md).

## 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](https://apione.ai/docs/en/support/contact.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.