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

# Errors

> Understand RISOS status codes, error envelopes, and safe recovery behavior.

REST errors use a structured envelope:

```json theme={null}
{
  "error": {
    "code": "API_SCOPE_REQUIRED",
    "message": "API_SCOPE_REQUIRED: research:write"
  }
}
```

Treat `error.code` as the machine-readable category and `error.message` as diagnostic context.

| Status | Meaning                                                           | Recovery                                                                      |
| ------ | ----------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `400`  | Input, validation, or request precondition failed.                | Correct the request; do not retry unchanged.                                  |
| `401`  | API key is missing, invalid, expired, or revoked.                 | Supply a current key.                                                         |
| `403`  | The key lacks the required scope.                                 | Use a least-privilege key that includes that scope.                           |
| `404`  | The resource or route is absent or not visible in this Workspace. | Verify the path, ID, and Workspace. Do not infer another tenant owns it.      |
| `429`  | Admission or rate limit reached.                                  | Honor `Retry-After` when present and back off with jitter.                    |
| `5xx`  | RISOS or a required provider is unavailable.                      | Retry safe reads; retry writes only with the documented idempotency strategy. |

For `POST /research-jobs`, preserve the same `Idempotency-Key` when retrying an uncertain request.