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

# Error code reference

> A quick reference for all error codes, HTTP statuses and troubleshooting tips

For the full error structure, see [API error codes](/en/api-reference/errors). 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         |

## 5xx server errors

| 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                                 |

## Task-API specific

| 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                  |

## Errors during streaming

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.

## General troubleshooting flow

<Steps>
  <Step title="Copy the Request ID">
    Get the ID from the `X-OpenPAI-Request-Id` response header.
  </Step>

  <Step title="Check the logs">
    Console → **Logs** → search for the Request ID to see the model, token usage and error code.
  </Step>

  <Step title="Verify the key">
    `curl https://openp.ai/v1/models -H "Authorization: Bearer sk-..."` to verify the key works.
  </Step>

  <Step title="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.
  </Step>
</Steps>