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

# Errors

> HTTP status codes Runflow returns and the error envelope shape.

## Envelope

Errors return a JSON body with `code`, `message`, and optional `errors[]`:

```json theme={"dark"}
{
  "code": "PERMISSION_DENIED",
  "message": "Your account is not authorized to access this resource.",
  "errors": null
}
```

| Field      | Type   | Notes                                                |
| ---------- | ------ | ---------------------------------------------------- |
| `code`     | string | Machine-friendly identifier. Stable across releases. |
| `message`  | string | Human-friendly message. May change.                  |
| `errors[]` | array  | Field-level details for `422 Unprocessable Entity`.  |

## Status codes

| Code  | Meaning                                  | Action                                                                                                                                                                                                        |
| ----- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | Bad request shape.                       | Check your JSON body against the spec.                                                                                                                                                                        |
| `401` | Missing or invalid token.                | Confirm `Authorization: Bearer <token>` is present and the key is active.                                                                                                                                     |
| `402` | Payment required.                        | Check the balance at [`GET /v1/billing/balance`](/api-reference/account/get-organization-credit-balance), then top up from [`app.runflow.io/settings/billing`](https://app.runflow.io/settings/billing).      |
| `403` | Permission denied or email not verified. | Check the `code` for `PERMISSION_DENIED` vs `EMAIL_NOT_VERIFIED`.                                                                                                                                             |
| `404` | Resource not found.                      | Verify the path and the resource ID.                                                                                                                                                                          |
| `409` | Conflict.                                | Usually a duplicate create or a race. Refetch and retry.                                                                                                                                                      |
| `422` | Validation error.                        | Read `errors[]` for per-field details.                                                                                                                                                                        |
| `503` | Service unavailable.                     | Backoff and retry with jitter. Check [`/v1/readiness`](https://api.runflow.io/v1/readiness) for component status, [contact support](https://cal.com/team/runflow/talk-to-founders?duration=25) if persistent. |

## Common codes

| `code`                | Cause                                                  |
| --------------------- | ------------------------------------------------------ |
| `UNAUTHORIZED`        | Bad or missing token.                                  |
| `PERMISSION_DENIED`   | Token lacks scope for this operation.                  |
| `EMAIL_NOT_VERIFIED`  | User has not confirmed their email.                    |
| `INSUFFICIENT_CREDIT` | Account balance is too low. Top up.                    |
| `RUN_NOT_FOUND`       | The `run_id` does not exist or belongs to another org. |
| `MODEL_UNAVAILABLE`   | Provider downtime. Retry or pick a sibling model.      |

## Run failures

When `POST /v1/models/.../runs` succeeds but the run later fails, the run object carries `failure_code`, `failure_stage`, and `failure_message`:

```json theme={"dark"}
{
  "id": "01J0...",
  "status": "failed",
  "failure_code": "INPUT_VALIDATION_FAILED",
  "failure_stage": "preprocess",
  "failure_message": "image dimensions exceed 4096x4096"
}
```

## Retry strategy

* `5xx` and `429`: exponential backoff with jitter, max 5 attempts.
* `4xx` other than `429`: do not retry, fix the request.
* Network errors: same as `5xx`.

## Related

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/concepts/authentication">401 and Bearer header detail.</Card>
  <Card title="Pricing" icon="coin" href="/concepts/pricing">402 and credit balance.</Card>
</CardGroup>