Errors

Envelope

All error responses share the same JSON shape:

{
  "ok": false,
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Maximum 60 requests per minute."
  }
}

HTTP	Code	When
400	`invalid_json`	Request body wasn't valid JSON.
400	`invalid_request`	JSON parsed but failed schema validation.
400	`unsupported_url`	URL didn't resolve to a supported provider receipt.
401	`missing_key`	No `x-api-key` header.
401	`invalid_key`	Key not recognised.
401	`revoked_key`	Key was revoked.
429	`rate_limited`	Hit your per-minute limit. Includes `Retry-After` seconds.
502	(none)	Upstream returned but the receipt failed validation. See `error` and partial `receipt`.
504	(none)	Upstream timeout (20 s).

429 — wait the Retry-After interval and try again.
502/504 — usually transient upstream glitches. Retry after 1–2 s with jitter; treat 3 consecutive failures as a real outage.
401 — never retry; mint a new key from the dashboard.