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

# Errors

> Sequentum returns RFC 7807 problem details on every error.

Errors are returned as JSON with the standard [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem-details shape:

```json theme={null}
{
  "type": "https://docs.sequentum.com/errors/agent-not-found",
  "title": "Agent not found",
  "status": 404,
  "detail": "No agent with id 4711 exists in space 1.",
  "instance": "/api/v1/agent/4711"
}
```

## HTTP status codes

| Code                | Meaning                                                                                 |
| ------------------- | --------------------------------------------------------------------------------------- |
| `200`               | OK — request succeeded.                                                                 |
| `201`               | Created — a new resource was created.                                                   |
| `202`               | Accepted — async work was queued (e.g., `start run`).                                   |
| `400`               | Bad request — invalid input. `detail` will explain.                                     |
| `401`               | Unauthorized — missing or invalid API key.                                              |
| `403`               | Forbidden — the key is valid but lacks access to the resource.                          |
| `404`               | Not found.                                                                              |
| `409`               | Conflict — usually a state-machine violation (e.g., `finish` on a `cancelled` session). |
| `422`               | Unprocessable entity — request was syntactically valid but semantically rejected.       |
| `429`               | Rate limited. Retry after the `Retry-After` header.                                     |
| `500`, `502`, `503` | Server error. Safe to retry with backoff.                                               |

## Rate limits

The API limits each API key to **100 requests per 60-second window** (with a small queue of 10 requests when the limit is reached). When you exceed the limit, you'll get `429 Too Many Requests`.

Three response headers communicate the limit on every request:

| Header                       | Meaning                                                            |
| ---------------------------- | ------------------------------------------------------------------ |
| `X-RateLimit-Limit`          | Max requests in the window (default: `100`).                       |
| `X-RateLimit-Window-Seconds` | Window length (default: `60`).                                     |
| `Retry-After`                | Seconds to wait before retrying — only present on `429` responses. |

If you're hitting the limit consistently, contact support — limits are config-driven per deployment and can be raised. Limits apply per API key, so distinct keys (e.g., per-environment) get independent budgets.

## Retries

Retry `5xx` and `429` responses with exponential backoff, respecting `Retry-After` when present. Do not retry `4xx` responses other than `429`.

`POST` endpoints are **not** currently idempotent. A retried `POST /agent/{id}/start` will queue a second Run — design your retry logic to check before retrying (e.g., poll `GET /agent/{id}/runs` for a recent in-flight Run before issuing another start).