Error code reference

Look up common HTTP statuses, asynchronous task error codes, and platform program error codes.

Error responses usually include both an HTTP status and a program error code in the response body. Applications should check the HTTP status first, then read the actual type, code, and message; fields may vary by protocol or upstream provider.

If you need to troubleshoot an observed issue, start with Errors and troubleshooting. This page is a reference for error meanings and does not replace the response documentation for a specific endpoint.

HTTP status

HTTP status	Common meaning	Common causes	Recommended action
`400`	Invalid request	The JSON, required fields, parameter types, file format, or input content does not meet the requirements	Correct the request based on the error message; do not retry it unchanged
`401`	Authentication failed	The API Key is missing or invalid, or the authentication header does not meet the protocol requirements	Check the Bearer or protocol-specific header and replace an invalid Key
`403`	Insufficient permission or quota	The account, Key, model permission, IP range, or available quota does not satisfy the request	Check account and Key restrictions and confirm that the target model is available
`404`	Resource not found	The endpoint, model ID, task ID, or video ID does not exist	Verify the final URL, resource ID, and owning account
`429`	Request limited	The request rate, concurrency, quota, or service capacity limit was reached	Reduce load and retry a limited number of times; save the Request ID if failures continue
`500`	Request processing failed	Request conversion, token calculation, pricing information, or platform processing failed	Save the redacted error details and Request ID, then retry a limited number of times later
`502`	Upstream gateway error	The upstream service returned an invalid response or the gateway could not complete forwarding	Retry a limited number of times; contact technical support if failures continue
`503`	Service temporarily unavailable	The platform or upstream service is overloaded, under maintenance, or has no processing capacity	Use backoff retries instead of continuous high-frequency requests
`504`	Request timed out	Upstream processing exceeded the gateway wait time	Record the Request ID; for asynchronous tasks, query the original task status first

An HTTP status alone does not determine the cause

A 404 may mean that a path, model, or task does not exist. A 429 may come from rate, concurrency, quota, or service capacity limits. Evaluate the actual error body together with the Request ID.

Common error envelopes

OpenAI-compatible endpoints commonly carry error information in an error object:

{
  "error": {
    "message": "The specific reason the request failed",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

Some platform task endpoints return code and message directly:

{
  "code": "task_not_exist",
  "message": "The requested task ID does not exist"
}

Clients should not assume that every endpoint uses exactly the same error envelope. Check the corresponding API Reference before parsing and handle missing optional fields safely.

Asynchronous task error codes

Midjourney tasks

`code`	HTTP status	Customer-facing meaning	Recommended action
`1`	`200`	Task submitted successfully	Save the returned task ID and query the progress endpoint
`4`	`400`	Invalid request parameters	Check the prompt, operation type, and required fields
`21`	`200`	An identical task already exists	Continue using the returned task ID; do not create a duplicate
`22`	`200`	The task is queued	Keep the task ID and query again later
`23`	`429`	The current task queue is full	Reduce the submission rate and retry later
`24`	`400`	The prompt did not pass content checks	Revise the prompt before submitting again
`3`	`403`	The current request cannot be submitted temporarily	Save the error details, then retry later or contact technical support
`30`	`429`	Processing capacity for the current group is full	Reduce concurrency and retry later

Example of a successful task submission:

{
  "code": 1,
  "description": "Submitted successfully",
  "result": "TASK_ID"
}

Example of a queued task:

{
  "code": 22,
  "description": "Queued with 2 tasks ahead"
}

Platform tasks

`code`	HTTP status	Customer-facing meaning	Recommended action
`task_not_exist`	`404`	The task does not exist or does not belong to the current account	Verify the task ID, API Key, and request site
`quota_not_enough`	`403`	The current quota is insufficient to create the task	Check the account and token quota; do not retry unchanged
`invalid_api_platform`	`400`	The platform type in the request is invalid	Correct the platform or protocol parameter
`fail_to_fetch_task`	Depends on the upstream status	The latest status could not be retrieved from the task source	Keep the current task ID and retry a limited number of times later

Platform program error codes

`code`	Common HTTP status	Customer-facing meaning	Recommended action
`invalid_request`	`400`	The request format or parameters are invalid	Check the JSON, required fields, and field types
`read_request_body_failed`	`400`	The request body could not be read	Check the body size, connection, and Content-Type
`sensitive_words_detected`	`400`	The input did not pass content checks	Revise the input before sending it again
`prompt_blocked`	`400`	The prompt was blocked by a content policy	Revise the prompt based on the error details
`access_denied`	`403`	The current request was denied	Check the API Key, account status, and allowed IP range
`insufficient_user_quota`	`403`	The account has insufficient available quota	Check the balance or quota before sending another request
`pre_consume_token_quota_failed`	`403`	The available token quota is insufficient	Check the current Key's quota and usage restrictions
`model_not_found`	`404`	The current account cannot find the target model	Copy an available model ID from the model marketplace
`convert_request_failed`	`500`	The request could not be converted to the target protocol	Verify the endpoint, protocol, and target model compatibility
`count_token_failed`	`500`	Token usage for the request could not be calculated	Save the redacted request characteristics and Request ID
`do_request_failed`	`500`	The platform could not complete the upstream request	Check network status and retry a limited number of times
`bad_response_status_code`	Depends on the upstream status	The upstream service returned a nonstandard error or one that could not be parsed directly	Save the original HTTP status, redacted message, and Request ID
`api_not_implemented`	`501`	The current endpoint is not available yet	Check the API Reference and use an endpoint that is already published

Client handling principles

Record the HTTP status, program error code, redacted message, and Request ID together.
For 400, 401, and 403, correct the cause first; do not automatically retry the same request.
For 404, verify the path and resource ID; for asynchronous resources, also verify the owning account.
For 429, 502, 503, and 504, use a limited number of backoff retries.
Before resending a task creation or another request with side effects, confirm whether the original request already took effect.
Do not branch program logic on the complete error message text. Prefer stable HTTP statuses and code values.

See Request ID for the tracing details to save, and Errors and troubleshooting for broader troubleshooting and retry guidance.