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

# Errors

> Error shape, status codes, and the canonical error catalog.

<Info>
  **BlobRouter v0.1** · Last updated: August 2026 · Architecture version: **2.0**
</Info>

## Response shape

All errors return JSON:

```json theme={null}
{
  "error": "Human readable message",
  "code": "error_code"
}
```

Optional `details` may appear for validation context. Stack traces are never returned.

Every response includes `X-Request-ID` — send that to support.

## Catalog

### Auth

| Code           | Status |
| -------------- | ------ |
| `unauthorized` | 401    |
| `forbidden`    | 403    |
| `plan_limit`   | 402    |

### Upload

| Code                      | Status |
| ------------------------- | ------ |
| `file_too_large`          | 400    |
| `invalid_size`            | 400    |
| `invalid_content_type`    | 400    |
| `invalid_filename`        | 400    |
| `file_not_on_provider`    | 400    |
| `no_providers_configured` | 400    |

### Routing

| Code                   | Status |
| ---------------------- | ------ |
| `routing_failed`       | 400    |
| `provider_unavailable` | 503    |

### Files

| Code                   | Status |
| ---------------------- | ------ |
| `file_not_found`       | 404    |
| `file_already_deleted` | 404    |

### Scanner

| Code                          | Status |
| ----------------------------- | ------ |
| `connection_failed`           | 400    |
| `scan_not_found`              | 404    |
| `scan_already_running`        | 409    |
| `invalid_role_arn`            | 400    |
| `credentials_missing`         | 400    |
| `scanner_credentials_missing` | 500    |

### Billing / system

| Code                  | Status |
| --------------------- | ------ |
| `payment_required`    | 402    |
| `billing_disabled`    | 503    |
| `encryption_error`    | 500    |
| `provider_error`      | 502    |
| `internal_error`      | 500    |
| `rate_limit_exceeded` | 429    |

## SDK

TypeScript and Python raise `BlobRouterError` with `code` and `statusCode` / `status_code`.