Errors, limits, pagination
The one error shape and every error code, rate limits and their headers, pagination, time ranges, idempotency, versioning and 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.
{
"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`
-
codestring requiredA stable, machine-readable reason. Branch on this. Codes are only ever added.
-
messagestring requiredWhat went wrong and what to do, written for a person. The wording may change: never parse it.
-
doc_urlURL requiredThe place on this page that explains the code.
-
request_idstring requiredThe id of the request. It is also in the
Sypnia-Request-Idheader of every response, successful or not. Quote it when you ask for help. -
paramstring optionalThe 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 - 400
invalid_body - 400
too_many_events - 401
unauthorized - 403
forbidden - 403
wrong_credential - 403
origin_not_allowed - 403
not_recordable - 403
cloud_managed - 404
not_found - 404
cloud_only - 409
conflict - 409
idempotency_conflict - 409
limit_reached - 409
ai_not_configured - 409
github_not_connected - 409
not_enough_evidence - 409
pull_request_exists - 410
expired - 413
payload_too_large - 415
unsupported_media_type - 422
session_full - 429
rate_limited - 429
limit_reached - 429
analysis_limit_reached - 429
fixes_limit_reached - 500
internal - 503
unavailable
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.
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:
{
"data": [ … ],
"next_cursor": "eyJ0IjoiMjAyNi0wMy0xMlQwOTo0OTowMloifQ"
}limitsets the page size: 1 to 200, default 50, unless an endpoint says otherwise.- To get the next page, repeat the same request with
cursorset tonext_cursor. Keep every other parameter the same. next_cursorisnullon 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, 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.