Errors & limits

Errors are standard HTTP status codes with a JSON detail. Every checker is free and rate-limited; a 429 tells you when you're over the limit and when it resets.

Error format

json

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

Status codes

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, or this week’s free checks are used up — the JSON detail is the sentence to show a person, and Retry-After (or a weekly reset time) tells you when to try again.
503	Metering unavailable	The usage meter could not be reached, so the call was not run. Transient — honour the Retry-After header and retry.
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.

Rate limits

Every checker is free: 20 checks a week without an account, 100 a week signed in — see /pricing. All of it also sits behind a short-window burst guard of ~10 requests.
429 responses include Retry-After — back off and respect it. Every response also carries RateLimit-Limit and RateLimit-Remaining — read them to self-throttle.
Hosted agents: connect with your account's API key or MCP connector URL. The same weekly limit applies; an anonymous connection gets the lower, no-account limit.

Idempotency

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.

Size & input caps

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.

Retry guidance

Don't retry 400, 413, or 501 — they won't change.
On 429 and 503, waitRetry-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.