Troubleshooting
Find the stable error code in the response, match it below, and follow the recommended recovery steps. Keep the request ID whenever you need support.
Identify the error
Use the stable x-owl-error-code response header when available. The response body also contains an HTTP status, message, and protocol-specific error type.
What to record
HTTP status: 429
x-owl-error-code: PLATFORM_RATE_LIMITED_CONCURRENCY
retry-after: 2
request_id: req_01K4...
endpoint: /v1/chat/completionsDo not send API keys, full prompts, image data, or other secrets to support. A request ID is sufficient for server-side correlation.
Request and model errors
| HTTP status | Error code | Meaning | Solution |
|---|---|---|---|
400 | CLIENT_INVALID_REQUEST | The request body, parameters, content type, or media combination is invalid. | Compare the request with the relevant API example. Check required fields, enum values, JSON syntax, and the Content-Type header. |
400 | CLIENT_CONTEXT_LENGTH_EXCEEDED | The prompt and requested output exceed the model context window. | Shorten conversation history or input content, then reduce max_tokens before retrying. |
400 / 404 | CLIENT_MODEL_NOT_FOUND / GENERATION_MODEL_NOT_FOUND | The requested model does not exist or is not currently available. | Fetch the current model list and use an exact model identifier. For video generation, use MiniMax-H3. |
404 | CLIENT_RESOURCE_NOT_FOUND | The resource or generation task cannot be found for this API key. | Check the resource ID and confirm that the same API key created the task. |
Authentication and permissions
| HTTP status | Error code | Meaning | Solution |
|---|---|---|---|
401 | CLIENT_API_KEY_INVALID | The API key is missing, malformed, expired, or revoked. | Send Authorization: Bearer followed by an active API key. Create a new key if the original value is no longer available. |
401 / 403 | CLIENT_API_KEY_DISABLED | The API key exists but has been disabled. | Enable the key in the console or replace it with another active key. |
403 | CLIENT_MODEL_NOT_ALLOWED / GENERATION_ACCESS_DENIED | The key is not allowed to use the requested model or video generation. | Edit the API key permissions and enable the required model or generative-model access. |
403 | CLIENT_IP_NOT_ALLOWED | The request source IP is outside the key allowlist. | Add the current egress IP to the key allowlist or send the request from an allowed network. |
Quota, billing, and rate limits
| HTTP status | Error code | Meaning | Solution |
|---|---|---|---|
402 | PLATFORM_PAYG_NOT_ENABLED | The request needs pay-as-you-go billing, but PAYG is disabled. | Enable PAYG in billing settings or use an active plan with available quota. |
402 | PLATFORM_BALANCE_INSUFFICIENT | The wallet does not have enough balance for the request. | Add funds or enable automatic reload, then submit the request again. |
402 / 429 | PLATFORM_QUOTA_EXHAUSTED / PLATFORM_TRIAL_EXHAUSTED | The active plan or trial has no remaining quota. | Wait for quota renewal, upgrade the plan, or enable PAYG if available. |
429 | PLATFORM_QUOTA_WINDOW_5H_EXHAUSTED / PLATFORM_QUOTA_WINDOW_WEEK_EXHAUSTED | The rolling five-hour or weekly allowance has been exhausted. | Check the Limits page for the reset time. Wait for the window to renew or use PAYG. |
402 / 429 | PLATFORM_API_KEY_SPEND_CAP_EXCEEDED | This API key reached its configured spending cap. | Increase the key spending cap or use another key with sufficient allowance. |
429 | PLATFORM_RATE_LIMITED / PLATFORM_RATE_LIMITED_RPM | Too many requests were sent in a short period. | Honor Retry-After when present and retry with exponential backoff and jitter. |
429 | PLATFORM_RATE_LIMITED_CONCURRENCY | The organization has reached its concurrent request limit. | Reduce parallel requests, queue work client-side, and retry after an active request finishes. |
Service and upstream errors
| HTTP status | Error code | Meaning | Solution |
|---|---|---|---|
503 | MODEL_CAPACITY_EXHAUSTED / MODEL_QUEUE_TIMEOUT / MODEL_OVERFLOW_FAILED | The selected model is busy or the request could not start before the queue deadline. | Retry with exponential backoff and jitter. Avoid immediately sending many identical retries. |
502 / 503 / 504 | MODEL_UPSTREAM_TIMEOUT / MODEL_UPSTREAM_UNAVAILABLE / MODEL_UPSTREAM_FAILURE | The upstream model timed out or is temporarily unavailable. | Retry transient failures with backoff. Preserve the request ID if the problem continues. |
503 | PLATFORM_BILLING_UNAVAILABLE / PLATFORM_DATABASE_UNAVAILABLE | Billing or persistence is temporarily unavailable, so the request cannot be safely processed. | Do not bypass billing checks. Retry after a short delay and contact support if the error persists. |
500 / 503 | PLATFORM_SERVICE_UNAVAILABLE / PLATFORM_UNEXPECTED_ERROR | An unexpected platform error occurred. | Retry once with backoff. If it fails again, contact support with request_id, timestamp, endpoint, and error code. |
Video API error types
The MiniMax-compatible video API uses its own error envelope. Match its type and HTTP code first, then use x-owl-error-code for the specific recovery path above.
| HTTP status | Error code | Meaning | Solution |
|---|---|---|---|
401 / 403 | authorized_error | Authentication or generation permission failed. | Check the API key, key status, and generative-model permission. |
400 / 402 | bad_request_error | The request is invalid or the balance is insufficient. | Check error.http_code and x-owl-error-code to distinguish request validation from balance errors. |
404 | not_found_error | The video task was not found for this key. | Verify task_id and use the same API key that created the task. |
429 | rate_limit_error | The video API rate limit was reached. | Wait for Retry-After when present, then retry with backoff. |
500 | server_error | The video service encountered an internal error. | Retry once, then contact support with request_id if it continues. |