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

# API Errors

> Standard error response format and common error messages returned by the Circuit API.

All endpoints return standard HTTP status codes and a consistent error response format.

### Error Response Format

All error responses follow this structure:

```typescript theme={null}
{
  success: false;
  error: string;
}
```

`5xx` (internal) errors always return the generic message `"Internal server error"` — the underlying detail is never leaked to the client.

### HTTP Status Codes

| Status        | When                                                              |
| ------------- | ----------------------------------------------------------------- |
| `400`         | Bad request — invalid or missing input                            |
| `401`         | Unauthorized — missing, invalid, revoked, or expired bearer token |
| `403`         | Forbidden — authenticated but not allowed for the resource        |
| `404`         | Not found — resource does not exist or is not visible             |
| `409`         | Conflict — request conflicts with current state                   |
| `412`         | Precondition failed                                               |
| `429`         | Too many requests — rate limited                                  |
| `502` / `503` | Upstream / service unavailable                                    |
| `500`         | Internal server error                                             |

### Typical Error Messages

| Status | Example Message                                              | Notes                                            |
| ------ | ------------------------------------------------------------ | ------------------------------------------------ |
| `400`  | `"Invalid request input"`                                    | Request body/query/path failed schema validation |
| `401`  | `"Missing Authorization: Bearer header"`, `"Permit revoked"` | Token missing, invalid, revoked, or expired      |
| `403`  | `"You are not authorized to stop this session"`              | Authenticated but not allowed for the resource   |
| `404`  | `"Agent not found"`, `"Session not found"`                   | Resource does not exist or is not visible        |
| `409`  | `"Wallet already exists"`                                    | Request conflicts with current state             |
| `500`  | `"Internal server error"`                                    | Unexpected backend error                         |