# Errors, limits, pagination

> The one error shape and every error code, rate limits and their headers, pagination, time ranges, idempotency, versioning and retention.

Applies to: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/api/errors-limits-pagination/

For agents: The conventions shared by every endpoint of the Sypnia API: error JSON shape and codes, when to retry, rate-limit headers, cursor pagination, since/until, environment, Idempotency-Key, versioning, retention.

**\[Engine]** **\[Cloud]** These rules hold for every endpoint of the API, on a self-hosted engine and on Sypnia Cloud.

## Errors

Every error has the same shape, and an HTTP status that says its class.

```json
{
  "error": {
    "code": "not_found",
    "message": "No problem with id or slug 'pay-button-does-nothin' in project 'shop'.",
    "doc_url": "https://docs.sypnia.com/api/errors-limits-pagination#not_found",
    "request_id": "req_4t7y1u9i3o5p"
  }
}
```

**Fields of \`error\`:**

- `code` (string, required): A stable, machine-readable reason. Branch on this. Codes are only ever added.
- `message` (string, required): What went wrong and what to do, written for a person. The wording may change: never parse it.
- `doc_url` (URL, required): The place on this page that explains the code.
- `request_id` (string, required): The id of the request. It is also in the `Sypnia-Request-Id` header of every response, successful or not. Quote it when you ask for help.
- `param` (string, optional): The parameter or body field at fault, when there is one. Body fields use dots: `settings.replay.sample_rate`.

| Status              | Meaning                                           | Retry?                        |
| ------------------- | ------------------------------------------------- | ----------------------------- |
| `400`               | The request is wrong                              | No. Fix it                    |
| `401`               | No valid credential                               | No                            |
| `403`               | The credential may not do this                    | No                            |
| `404`               | It does not exist in this project                 | No                            |
| `409`               | It does not fit the current state                 | Only after changing something |
| `410`               | It existed and is past retention                  | No                            |
| `413`, `415`, `422` | The body is too large, the wrong type, or refused | No                            |
| `429`               | Too many requests, or a limit reached             | Yes, after `Retry-After`      |
| `500`               | The engine failed                                 | Yes, with backoff             |
| `503`               | The engine cannot reach its database or storage   | Yes, after `Retry-After`      |

**Error codes:**

- `400` `invalid_request`: A parameter or the body is wrong. `param` names it and `message` says what is expected.
- `400` `invalid_body`: The body could not be read: not JSON, not valid gzip, or not the expected shape. Ingest and OTLP only.
- `400` `too_many_events`: An ingest batch has more than 200 events.
- `401` `unauthorized`: No credential, or one that is unknown, revoked or expired.
- `403` `forbidden`: The credential is valid and lacks the scope this call needs, or names a project it does not belong to. `message` names the missing scope.
- `403` `wrong_credential`: The wrong kind of credential: an API token on an ingest endpoint, or an ingest key anywhere else.
- `403` `origin_not_allowed`: Browser ingest from an origin that is not in the project's `allowed_origins`.
- `403` `not_recordable`: A replay chunk or page snapshot for a route where recording is switched off.
- `403` `cloud_managed`: Something Sypnia Cloud manages in the app, such as creating a project, was asked through the API.
- `404` `not_found`: The thing does not exist in this project. Also what you get for something that exists in another project: the API never confirms it.
- `404` `cloud_only`: A Sypnia Cloud endpoint was called on a self-hosted engine.
- `409` `conflict`: The call does not fit the current state. `message` says why.
- `409` `idempotency_conflict`: The `Idempotency-Key` was used before with a different body.
- `409` `limit_reached`: A fixed number of things is used up: keys, tokens, webhooks, uptime checks.
- `409` `ai_not_configured`: The call needs the agent and no AI provider is configured, or the project switched the agent off.
- `409` `github_not_connected`: Sypnia Cloud: the project has no repository connected.
- `409` `not_enough_evidence`: Sypnia Cloud: a pull request was asked for a problem whose analysis cannot justify a fix.
- `409` `pull_request_exists`: Sypnia Cloud: the problem already has an open pull request.
- `410` `expired`: The data existed and is past the project's retention.
- `413` `payload_too_large`: The body is over the limit of the endpoint.
- `415` `unsupported_media_type`: The `Content-Type` is not one the endpoint reads.
- `422` `session_full`: A replay chunk for a session that already has 720 chunks.
- `429` `rate_limited`: Too many requests. Wait for `Retry-After`.
- `429` `limit_reached`: Ingest only: the project reached a usage limit for this kind of data. The answer carries `slow_down`.
- `429` `analysis_limit_reached`: The project used its analyses for today.
- `429` `fixes_limit_reached`: Sypnia Cloud: the organization used this month's pull requests.
- `500` `internal`: The engine failed. It is our bug or, self-hosted, a broken deployment: `sypnia doctor` tells which. Safe to retry.
- `503` `unavailable`: The engine cannot reach its database or its storage right now. Retry after `Retry-After` (2 seconds by default).

### Retrying

Retry `429`, `500`, `503` and network failures. Wait for `Retry-After` when it is there; otherwise wait 1 second, then 4, then 15, and stop. `GET` and `DELETE` are always safe to repeat. For `POST`, send an [`Idempotency-Key`](#idempotency).

## Rate limits

Each API token may make **600 requests a minute**. Search is limited to 60 a minute and `POST …/analyze` to 10 a minute, inside the same budget. On a self-hosted engine the number is yours to set (`SYPNIA_RATE_LIMIT_API_PER_MINUTE`, `0` for none), and it is counted per process, so an engine that runs several processes allows somewhat more.

Ingest is limited per ingest key and per address: 600 requests a minute by default, set per key.

Every response of the API carries:

| Header                | Meaning                                    |
| --------------------- | ------------------------------------------ |
| `RateLimit-Limit`     | Requests allowed in the current window     |
| `RateLimit-Remaining` | Requests left in the window                |
| `RateLimit-Reset`     | Seconds until the window resets            |
| `Retry-After`         | Only with `429` and `503`: seconds to wait |

A `429 rate_limited` means slow down and try again. A `429` with another code (`limit_reached`, `analysis_limit_reached`, `fixes_limit_reached`) means a usage limit: waiting a few seconds will not help, `Retry-After` says when the limit resets.

## Pagination

Lists return a page and a cursor:

```json
{
  "data": [ … ],
  "next_cursor": "eyJ0IjoiMjAyNi0wMy0xMlQwOTo0OTowMloifQ"
}
```

- `limit` sets the page size: 1 to 200, default 50, unless an endpoint says otherwise.
- To get the next page, repeat the same request with `cursor` set to `next_cursor`. Keep every other parameter the same.
- `next_cursor` is `null` on the last page.
- A cursor is opaque and works for 24 hours. An expired or altered cursor is `400 invalid_request`.
- Pages are stable: an item that arrives while you page does not shift the ones you have not read.

There are no page numbers and no total counts, except where an endpoint returns `counts`.

## Time ranges

Endpoints that read over time take `since` and `until`.

| Form     | Example                | Meaning                                                       |
| -------- | ---------------------- | ------------------------------------------------------------- |
| Relative | `30m`, `24h`, `7d`     | That long before now. Units: `m` minutes, `h` hours, `d` days |
| Absolute | `2026-03-12T09:00:00Z` | An ISO 8601 timestamp. Without a zone it is read as UTC       |

`until` defaults to now. Each endpoint has its own default for `since`. A range that reaches before the project's retention is cut to it, silently. When days matter (daily buckets, «today»), they are cut at midnight in the project's time zone.

## Environment

Read endpoints take `environment`. The default is `production`. Pass any environment name your app has sent, or `all`. The same failure in two environments is two problems, so tests in `development` never mix with production.

## Idempotency

`POST` requests that create something accept an `Idempotency-Key` header: any string of 1 to 255 characters that you choose, such as a UUID.

- The first response for a key is stored for 24 hours.
- The same key with the same body gets that response again, with the header `Idempotent-Replayed: true`. Nothing is created twice.
- The same key with a different body is `409 idempotency_conflict`.

Ingest does not use this header. A batch of events is made safe to repeat by its `batch_id`, and a replay chunk by its `seq`.

## Versioning

The version is the `/v1` in the path. Inside `v1` things are only added: new endpoints, new optional parameters, new fields in responses, new values in lists of allowed values, new error codes. Nothing is renamed or removed. So a client must ignore fields it does not know and must not fail on a value it has not seen.

A change that breaks this would be `/v2`, announced in the [changelog](https://docs.sypnia.com/reference/changelog), with `/v1` kept working for at least 12 months.

Every response carries `Sypnia-Version`, the version of the engine that answered.

## Retention

Data is deleted when it passes its retention. After that, reading it answers `410 expired`, or it is absent from lists.

| Data                                               | Self-hosted engine (default, yours to change) | Sypnia Cloud                |
| -------------------------------------------------- | --------------------------------------------- | --------------------------- |
| Events, sessions and their timelines, traces       | 90 days                                       | The plan's days             |
| Replay recordings                                  | 30 days                                       | The plan's days, at most 30 |
| Page snapshots                                     | 90 days                                       | The plan's days             |
| Hourly and daily numbers                           | 400 days                                      | 400 days                    |
| Source maps                                        | 90 days after the release was last seen       | The same                    |
| Problems: sentence, analysis, status, daily counts | While the project exists                      | While the project exists    |

`GET /v1/usage` returns the retention that applies to a project.
