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

# Errors

> Every response is an envelope. Successes carry data. Failures carry a stable code you can branch on.

A successful response has `status: "success"` and a `data` object. A failure has `status: "error"` and an `error` object.

```json theme={null}
{
  "status": "error",
  "error": {
    "message": "Unsupported rail 'foo'",
    "code": "UNSUPPORTED_RAIL"
  }
}
```

<ResponseField name="status" type="string" required>
  Always `error` on failure.
</ResponseField>

<ResponseField name="error.message" type="string" required>
  Human-readable explanation. Safe to show a developer; do not parse it.
</ResponseField>

<ResponseField name="error.code" type="string" required>
  Stable machine-readable code. Branch on this.
</ResponseField>

<ResponseField name="error.details" type="array">
  Optional extra context — validation messages, and so on.
</ResponseField>

## HTTP status codes

| Status | Meaning                                                              |
| ------ | -------------------------------------------------------------------- |
| `200`  | Success.                                                             |
| `201`  | Created (a thread).                                                  |
| `202`  | Accepted (a run or an outcome).                                      |
| `400`  | Bad request — missing or illegal parameters.                         |
| `401`  | Missing or invalid credential.                                       |
| `402`  | Workspace is out of credits.                                         |
| `403`  | Authenticated, but not allowed (realtime channel, unverified email). |
| `404`  | The referenced resource does not exist.                              |
| `409`  | Conflict.                                                            |
| `422`  | The request was understood but cannot be processed.                  |
| `429`  | Rate limited.                                                        |
| `500`  | Something broke on our side.                                         |

## Error codes

| Code                    | Status | When                                                                          |
| ----------------------- | ------ | ----------------------------------------------------------------------------- |
| `MISSING_PARAMETER`     | `400`  | A required field was omitted (`rail`, `code`, …).                             |
| `UNSUPPORTED_RAIL`      | `400`  | `rail` is not one Identify supports.                                          |
| `INVALID_CODE`          | `400`  | The identifier failed validation (malformed NUBAN, bad IBAN check digits, …). |
| `UNAUTHORIZED`          | `401`  | Missing or invalid API key or session token.                                  |
| `INSUFFICIENT_CREDITS`  | `402`  | Identify — workspace balance is empty.                                        |
| `insufficient_credits`  | `402`  | Loom — workspace balance is empty.                                            |
| `FORBIDDEN`             | `403`  | Not allowed on this resource.                                                 |
| `NOT_FOUND`             | `404`  | Unknown thread, run, agent, or action.                                        |
| `unknown_action`        | `404`  | Outcome posted for a tool call that is not a pending proposed action.         |
| `VALIDATION_ERROR`      | `422`  | A field was present but failed model validation.                              |
| `not_awaiting_outcome`  | `422`  | Outcome posted against a run that is not waiting.                             |
| `invalid_state`         | `422`  | Outcome `state` is not `occurred` or `failed`.                                |
| `connection_required`   | `422`  | The agent has unpinned customer tools and no connection was named.            |
| `RATE_LIMITED`          | `429`  | Burst or sustained limit hit. Honor `Retry-After`.                            |
| `INTERNAL_SERVER_ERROR` | `500`  | Unexpected failure.                                                           |

Loom connection errors (`unknown_connection`, `connection_locked`, `connection_mismatch`) are `400` or `422` depending on the path. The `message` explains which.

<Note>
  Identify codes are `SCREAMING_SNAKE`. A few Loom codes are `snake_case`. Match the string exactly.
</Note>