Error code reference

For the full error structure, see API error codes. This page is a quick reference.

4xx client errors

HTTP	code	Troubleshooting
400	`invalid_request_error`	Check the request body JSON format and required fields
400	`invalid_model`	Model ID spelling or token allowlist
400	`context_length_exceeded`	Shorten the input / switch to a large-context model
400	`unsupported_modality`	The model doesn’t support image / audio input
400	`invalid_parameter`	A field value is out of range (e.g. temperature > 2)
401	`invalid_api_key`	Key doesn’t exist / wrong format / contains a newline
401	`expired_api_key`	Token expired — extend it or create a new one
401	`disabled_api_key`	Token disabled — enable it or create a new one
403	`insufficient_quota`	Account or token quota exhausted — top up
403	`model_not_allowed`	Edit the token to add this model
403	`ip_not_allowed`	The source IP isn’t in the allowlist
404	`model_not_found`	Model retired or misspelled
404	`resource_not_found`	The task / file doesn’t exist
413	`request_too_large`	The request body exceeds the 32MB limit
422	`validation_error`	Schema validation failed
429	`rate_limit_exceeded`	RPM / TPM hit — back off and retry
429	`concurrent_limit_exceeded`	Concurrency ceiling exceeded
429	`upstream_rate_limited`	Upstream 429 — the client should also back off

HTTP	code	Troubleshooting
500	`server_error`	Internal gateway error, usually auto-retried. To report, include the Request ID
502	`bad_gateway`	The upstream returned an invalid response
503	`upstream_unavailable`	All upstream channels are temporarily unavailable — wait or switch models
504	`upstream_timeout`	Upstream timed out — shorten the input or retry

code	Applies to	Notes
`task_failed`	Midjourney / Suno / Sora	The task failed upstream — see `failure_reason`
`task_not_found`	Async tasks	The task ID doesn’t exist or is past its retention period
`task_queue_full`	Async tasks	The upstream queue is full — retry later

When a streaming 200 response errors midway, it is sent as SSE:

data: {"error":{"message":"...","type":"server_error","code":"upstream_timeout"}}
data: [DONE]

Always check the error field when consuming SSE.

Copy the Request ID

Get the ID from the X-OpenPAI-Request-Id response header.

Check the logs

Console → Logs → search for the Request ID to see the model, token usage and error code.

Verify the key

curl https://openp.ai/v1/models -H "Authorization: Bearer sk-..." to verify the key works.

Keep the details

If you still can’t pin it down, record the Request ID, the time of the error, and reproduction steps for later investigation.