# Errors

## How to read an error

HTTP status describes the request to the API. `error.code` describes the reason for failure. They are separate fields: **HTTP 200 is not a business error code.**

* A rejected submission returns an HTTP error status with an `error` object.
* A successful task query returns HTTP 200. Read `status` to determine whether generation is `processing`, `completed`, or `failed`.
* For a failed task, branch on `error.code`, not on the text in `message`. Different failure reasons have different codes; the same reason uses the same code across models.
* `60002` is the fallback when a more specific public cause cannot be determined. Handle unrecognized future codes as a generic failure.

{/* error-catalog:start */}

## Request errors

These HTTP statuses describe a rejected or unconfirmed submission, or a failed task query. A submission timeout does not prove that no task was created.

| Error code (`error.code`) | HTTP status   | Meaning                                                                       | Next step                                                                       |
| ------------------------- | ------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `10001`                   | 401           | The API key is missing or invalid.                                            | Check the Authorization header and API key.                                     |
| `10002`                   | 403           | You do not have permission to make this request.                              | Check access permissions.                                                       |
| `20001`                   | 400, 413, 422 | The request was rejected. Check the parameters against the API documentation. | Correct the request parameters before retrying.                                 |
| `20002`                   | 400           | The requested model is not available.                                         | Select a model listed in the model catalog.                                     |
| `30001`                   | 402           | Not enough credits to run this request.                                       | Add credits before submitting.                                                  |
| `30002`                   | 429           | Too many requests. Please wait and try again.                                 | Wait and retry with backoff. Do not repeat accepted submissions.                |
| `50001`                   | 404           | Task not found.                                                               | Check the task ID and use the owning account’s key.                             |
| `50002`                   | 503           | Submission could not be confirmed. Check your tasks before submitting again.  | Check task history before submitting again; the request may have been accepted. |
| `90001`                   | 503           | The service is temporarily unavailable.                                       | Back off; retain any task ID already received.                                  |

## Task failures

A successful task query returns HTTP 200 even when generation failed. Check `status: "failed"` and `error.code` in the response. These codes describe the task outcome, not the HTTP request. Failed tasks are not charged.

| Error code (`error.code`) | Meaning                                                                                   | Next step                                           |
| ------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `20001`                   | The request was rejected. Check the parameters against the API documentation.             | Correct the request parameters before retrying.     |
| `50003`                   | The task did not complete within the allowed time. Please try again.                      | The task is not charged. You may submit a new task. |
| `60001`                   | The request was rejected by the content policy. Please revise the prompt or input images. | Revise the prompt or media input.                   |
| `60002`                   | Generation could not be completed. Please try again.                                      | The task is not charged. You may submit a new task. |
| `60003`                   | No output was generated. Please revise the prompt or try again.                           | Revise the input or submit a new task.              |
| `60004`                   | The generated output could not be delivered. Please try again.                            | The task is not charged. Try again later.           |
| `90001`                   | The service is temporarily unavailable.                                                   | Back off; retain any task ID already received.      |

{/* error-catalog:end */}

```json
{
  "id": "task_...",
  "status": "failed",
  "error": {
    "code": 60002,
    "message": "Generation could not be completed. Please try again."
  }
}
```

If submission itself times out, check your task history before submitting again: the first request may have been accepted.