Fictura
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

StatuserrorMeaning
400validation_error / invalid_bodyThe 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.
400invalid_rangeA malformed or inverted date range; parameter names the culprit (on Bulk export, message says what is wrong).
400invalid_limit / invalid_cursor / invalid_time / invalid_eventA bad query parameter on the Events or Persons API.
400missing x-app-idA dashboard-session request without the header.
400empty_patchA PATCH with nothing to change.
400too_many_eventsAn ingest batch over 500 events; max carries the limit. Split the batch.
401missing x-api-key / unauthorizedNo key, or a key Fictura doesn't recognize.
401missing_key / invalid_keyThe Links and Data APIs' equivalents for the Bearer key.
402subscription_requiredA dashboard-session request for an app with no active subscription. Key-authenticated routes do not check this, so ingestion keeps running.
403forbiddenAuthenticated, but not a member of the app in x-app-id.
403missing_scopeA Data API key without the route's scope; message names it.
403historical_requires_import_keyhistorical: true without a matching key. See Historical import.
403account_suspendedThe account is switched off, for dashboard sessions, SDK keys and Data API keys alike; message carries the reason.
404not_foundThe resource doesn't exist — or isn't yours, which is deliberately the same answer.
409slug_takenA link slug already in use.
400 / 422invalid_config / invalid_credentials / provider_errorSemantically 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.
429rate_limitedOver a rate limit. Back off; event and error ingestion also send Retry-After (seconds) and retry_after.
503encryption_not_configuredThe server can't store credentials; hint says what's missing.
503storage_not_configuredBulk export has nowhere to write its file.
503startingThe server is still starting. Retry shortly.
500internal_errorOurs, 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.

On this page