Overview
Errors
Every JSON response carries ok; every error names itself with a code. Read the code, not the prose.
Error — application/json
{
"ok": false,
"error": "validation_error",
"details": [
{ "path": ["events"], "message": "Required" }
]
}Success responses are {"ok": true, …}; failures are {"ok": false, "error": "<code>"}, sometimes with message, hint, details, or issues giving specifics. Match on error, never on the human text. The exceptions speak another format: file downloads, qr.svg and OTLP traces.
Codes you'll actually meet
| Status | error | Meaning |
|---|---|---|
| 400 | validation_error / invalid_body | The body failed schema validation. validation_error carries details; invalid_body on the Links API and Bulk export carries issues; the error-ingest endpoint answers a bare invalid_body, or adds per-event results when every event in the batch is invalid. |
| 400 | invalid_range | A malformed or inverted date range; parameter names the culprit (on Bulk export, message says what is wrong). |
| 400 | invalid_limit / invalid_cursor / invalid_time / invalid_event | A bad query parameter on the Events or Persons API. |
| 400 | missing x-app-id | A dashboard-session request without the header. |
| 400 | empty_patch | A PATCH with nothing to change. |
| 400 | too_many_events | An ingest batch over 500 events; max carries the limit. Split the batch. |
| 401 | missing x-api-key / unauthorized | No key, or a key Fictura doesn't recognize. |
| 401 | missing_key / invalid_key | The Links and Data APIs' equivalents for the Bearer key. |
| 402 | subscription_required | A dashboard-session request for an app with no active subscription. Key-authenticated routes do not check this, so ingestion keeps running. |
| 403 | forbidden | Authenticated, but not a member of the app in x-app-id. |
| 403 | missing_scope | A Data API key without the route's scope; message names it. |
| 403 | historical_requires_import_key | historical: true without a matching key. See Historical import. |
| 403 | account_suspended | The account is switched off, for dashboard sessions, SDK keys and Data API keys alike; message carries the reason. |
| 404 | not_found | The resource doesn't exist — or isn't yours, which is deliberately the same answer. |
| 409 | slug_taken | A link slug already in use. |
| 400 / 422 | invalid_config / invalid_credentials / provider_error | Semantically invalid config (400 on the web-checkout save, 422 on paywalls and onboarding), or an upstream provider rejected what you gave it — message carries the provider's reason. |
| 429 | rate_limited | Over a rate limit. Back off; event and error ingestion also send Retry-After (seconds) and retry_after. |
| 503 | encryption_not_configured | The server can't store credentials; hint says what's missing. |
| 503 | storage_not_configured | Bulk export has nowhere to write its file. |
| 503 | starting | The server is still starting. Retry shortly. |
| 500 | internal_error | Ours, not yours. |
One deliberate 200
An unknown user on the entitlements endpoint is not an error — it answers 200 with status: "none", so one code path handles known and unknown users alike.