Guides / Troubleshooting

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:         /v2/video_generation

Do 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 / 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 its model ID. Video model matching ignores case; verify that your API key can access the selected model.
`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.	Create an API key with the required model selected.
`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`	`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 selected video model.
`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.