Errors & limits

Errors are standard HTTP status codes with a JSON detail message. Limits are per IP while the service is free.

Error format

json

{ "detail": "Document exceeds the 25 MB limit." }

Parameter	Type	Description
400	Bad request	Invalid input — empty document, malformed JSON/base64/id, or a URL the SSRF guard refused (non-public host).
401	Unauthorized	An Authorization header was presented but the API key is invalid or disabled. Anonymous calls (no header) are never 401.
404	Not found	No warrant or fact-check exists for that id.
413	Too large	The document (or fetched URL body) exceeds the 25 MB cap.
422	Validation / conflict	The request body does not match the schema (e.g. an unknown feedback verdict), or an Idempotency-Key was reused with a different payload.
429	Rate limited	Too many requests — honour the Retry-After header.
501	Not implemented	URL intake on /v1/warrants — send file or bytes_b64, or use the MCP verify_document tool, which accepts a url.
502	Fetch failed	A {"url": ...} document could not be fetched from its host.

Anonymous: 20 documents/day per IP. With a free API key: 50/day on your own quota. Both sit behind a short-window burst guard of ~10 requests.
429 responses include Retry-After — back off and respect it.
Every response carries RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset (seconds until the daily quota resets at 00:00 UTC) — read them to self-throttle.
Hosted agents note: anonymous callers behind one egress IP share a budget — get a key and the quota is yours alone.

Send an Idempotency-Key header on any POST /v1/* call. The first request runs; a retry with the same key replays the stored response instead of processing again — so a network retry never double-processes.
Reusing a key with a different request body returns 422. Keys are remembered for 24 hours; streaming calls (?stream=1) are exempt.

25 MB max document size — uploads and URL fetches alike.
Inputs: PDF, or images (.png .jpg .jpeg .webp .bmp .tif) for forensics; PDF/text/HTML for the analysis tools.
URL intake fetches public http(s) hosts only; redirects are re-validated hop by hop.

Don't retry 400, 413, or 501 — they won't change.
On 429, wait Retry-After seconds.
On a streamed error event or 5xx, back off exponentially — failures are usually transient.
Use ?stream=1 for deep fact-checks and image forensics rather than holding a blocking request open.
Cache-check first (GET /v1/warrants/check) — identical bytes are already deduplicated by content hash.