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

# Errors

> One envelope, a stable code vocabulary, and a retryable flag you can act on.

```json theme={null}
{
  "error": {
    "code": "rate_limited",
    "message": "The source temporarily rate limited acquisition.",
    "retryable": true,
    "requestId": "req_01a0…",
    "details": {}
  }
}
```

`details` is an allow-listed subset per code, for example `field` and `reason` for `invalid_input` or `resourceType` for `not_found`. Messages are safe to show to users; they never echo source diagnostics.

## Codes

| Code                                                         | HTTP | `retryable`           | When                                                            |
| ------------------------------------------------------------ | ---- | --------------------- | --------------------------------------------------------------- |
| `invalid_input`                                              | 400  | no                    | Malformed body, unsupported URL form, bad cursor                |
| `credential_conflict`                                        | 400  | no                    | Cookie and bearer on one request                                |
| `unauthenticated` / `invalid_credential`                     | 401  | no                    | Missing or invalid credential                                   |
| `forbidden` / `policy_blocked`                               | 403  | no                    | Scope, role, or policy does not allow the action                |
| `not_found`                                                  | 404  | no                    | Unknown or foreign-workspace resource                           |
| `revision_conflict`                                          | 409  | yes, after re-reading | Stale `revision` on an update                                   |
| `idempotency_conflict`                                       | 409  | no                    | Same key, different body                                        |
| `unavailable_removed`                                        | 410  | no                    | The source object is gone                                       |
| `limit_exceeded`                                             | 413  | no                    | Bytes, duration, or height above the route limit                |
| `unavailable_private` / `unavailable_restricted`             | 422  | no                    | The source will not serve the object publicly                   |
| `unsupported_object` / `unsupported_media` / `media_invalid` | 422  | no                    | Live, premiere, playlist, DRM, or media that fails verification |
| `rate_limited`                                               | 429  | yes                   | Slow down; `details.retryAfterSeconds` says how long            |
| `internal_error`                                             | 500  | no                    | Our bug; the `requestId` helps us find it                       |
| `source_changed`                                             | 502  | no                    | The source no longer matches the supported contract             |
| `network_transport`                                          | 502  | yes                   | Upstream transport failed                                       |
| `route_disabled` / `route_degraded`                          | 503  | degraded only         | Source route not available to the workspace                     |
| `storage_unavailable` / `retry_exhausted`                    | 503  | storage only          | Object storage hiccup, or the worker used up its retry budget   |
| `network_timeout`                                            | 504  | yes                   | Upstream timed out                                              |

The TypeScript SDK exposes the same information as `RefmatterError` with `status`, `code`, `requestId`, and `retryable`.