Developer API · v1.1

Errors & Rate Limits

Errors are returned with a standard HTTP status and a JSON body. A successful verification is always 200, and a citation that fails to verify is a verdict, not an HTTP error.

Error responses

Non-200 responses share this shape:

{ "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded. Retry after the indicated interval." } }

Status	Meaning	What to do
`401` Unauthorized	Missing or malformed `Authorization` header.	Send `Authorization: Bearer <API_KEY>`. Do not retry until fixed.
`403` Forbidden	The key is valid but not permitted (e.g. revoked or out of entitlement).	Check the key in Developer Tools; regenerate if needed. Do not retry blindly.
`422` Unprocessable	The request body is malformed or fails validation (e.g. missing `items`, bad `type`).	Fix the payload against the API Reference. Do not retry unchanged.
`429` Too Many Requests	Rate limit or quota exceeded.	Back off and retry after `Retry-After` (see below).
`500` Server Error	An unexpected error on our side.	Retry with exponential backoff; if it persists, contact support.

Quota & billing

Every 200 response includes a usage object with your quota for the current window:

"usage": { "used": 1, "remaining": 99, "limit": 100 }

usage.used: quota consumed so far in the window.
usage.remaining: quota still available. This is your primary signal for pacing, so slow down before it reaches 0.
usage.limit: the ceiling for the window.

Read quota from the response, not from HTTP headers. Pace on the usage object in the JSON body. The API does not emit X-RateLimit-* headers; the only rate-related header is Retry-After, and only on a 429 (see below). Do not hard-code the limit, treat usage.limit as the source of truth, as it may differ between accounts and can change over time.

What counts against billing

Every 200 response also includes a summary with two accounting fields:

summary.unique_citations: the number of distinct citations in the request. Identical citations submitted more than once are counted once.
summary.billed_citations: the number of citations you were billed for.

Quotations (type: "quote") are not counted as billed citations; a quotation is verified against its parent case and does not add to billed_citations. So duplicate citations and quotations do not each incur a separate charge. Reconcile against these fields rather than counting raw items.

Rate limiting

If you exceed the allowed rate or quota, the API returns 429.

Retry behavior for 429

A 429 includes a Retry-After header (seconds to wait):

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Honor it:

Wait at least Retry-After seconds before the next request.
Add jitter and exponential backoff if you retry repeatedly.
Prefer batching multiple items into one request (the items array) over many single-item requests.

Which failures to retry

Retry: 429 (after Retry-After) and 500 (with backoff).
Do not retry unchanged: 401, 403, 422, which need a fix (credentials or payload), not a repeat.

Remember: a hallucinated or unresolved citation is not an HTTP error. It comes back 200 with a critical or warning verdict. Only genuine transport/auth/quota problems produce 4xx/5xx.