Docs

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 EngineCloud At launch

View as Markdown
On this page
  1. Errors
  2. Retrying
  3. Rate limits
  4. Pagination
  5. Time ranges
  6. Environment
  7. Idempotency
  8. Versioning
  9. 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.

StatusMeaningRetry?
400The request is wrongNo. Fix it
401No valid credentialNo
403The credential may not do thisNo
404It does not exist in this projectNo
409It does not fit the current stateOnly after changing something
410It existed and is past retentionNo
413, 415, 422The body is too large, the wrong type, or refusedNo
429Too many requests, or a limit reachedYes, after Retry-After
500The engine failedYes, with backoff
503The engine cannot reach its database or storageYes, after Retry-After

Error codes

  • 400invalid_request

    A parameter or the body is wrong. param names it and message says what is expected.

  • 400invalid_body

    The body could not be read: not JSON, not valid gzip, or not the expected shape. Ingest and OTLP only.

  • 400too_many_events

    An ingest batch has more than 200 events.

  • 401unauthorized

    No credential, or one that is unknown, revoked or expired.

  • 403forbidden

    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.

  • 403wrong_credential

    The wrong kind of credential: an API token on an ingest endpoint, or an ingest key anywhere else.

  • 403origin_not_allowed

    Browser ingest from an origin that is not in the project’s allowed_origins.

  • 403not_recordable

    A replay chunk or page snapshot for a route where recording is switched off.

  • 403cloud_managed

    Something Sypnia Cloud manages in the app, such as creating a project, was asked through the API.

  • 404not_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.

  • 404cloud_only

    A Sypnia Cloud endpoint was called on a self-hosted engine.

  • 409conflict

    The call does not fit the current state. message says why.

  • 409idempotency_conflict

    The Idempotency-Key was used before with a different body.

  • 409limit_reached

    A fixed number of things is used up: keys, tokens, webhooks, uptime checks.

  • 409ai_not_configured

    The call needs the agent and no AI provider is configured, or the project switched the agent off.

  • 409github_not_connected

    Sypnia Cloud: the project has no repository connected.

  • 409not_enough_evidence

    Sypnia Cloud: a pull request was asked for a problem whose analysis cannot justify a fix.

  • 409pull_request_exists

    Sypnia Cloud: the problem already has an open pull request.

  • 410expired

    The data existed and is past the project’s retention.

  • 413payload_too_large

    The body is over the limit of the endpoint.

  • 415unsupported_media_type

    The Content-Type is not one the endpoint reads.

  • 422session_full

    A replay chunk for a session that already has 720 chunks.

  • 429rate_limited

    Too many requests. Wait for Retry-After.

  • 429limit_reached

    Ingest only: the project reached a usage limit for this kind of data. The answer carries slow_down.

  • 429analysis_limit_reached

    The project used its analyses for today.

  • 429fixes_limit_reached

    Sypnia Cloud: the organization used this month’s pull requests.

  • 500internal

    The engine failed. It is our bug or, self-hosted, a broken deployment: sypnia doctor tells which. Safe to retry.

  • 503unavailable

    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.

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:

HeaderMeaning
RateLimit-LimitRequests allowed in the current window
RateLimit-RemainingRequests left in the window
RateLimit-ResetSeconds until the window resets
Retry-AfterOnly 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.

FormExampleMeaning
Relative30m, 24h, 7dThat long before now. Units: m minutes, h hours, d days
Absolute2026-03-12T09:00:00ZAn 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.

DataSelf-hosted engine (default, yours to change)Sypnia Cloud
Events, sessions and their timelines, traces90 daysThe plan’s days
Replay recordings30 daysThe plan’s days, at most 30
Page snapshots90 daysThe plan’s days
Hourly and daily numbers400 days400 days
Source maps90 days after the release was last seenThe same
Problems: sentence, analysis, status, daily countsWhile the project existsWhile the project exists

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

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close