Skip to main content
When a request fails, the API answers with an HTTP error status and a JSON problem document (RFC 9457). Every error has the same shape, so one handler covers them all.

Shape

Problem documents never include stack traces, the key you sent, or data from another workspace.

Problem types

The catalog has one more code, method_not_allowed (405), which the MCP endpoint uses when it receives anything but POST. Most REST endpoints accept only GET and HEAD. The facts endpoints also accept POST on /projects/{project_id}/facts, and PATCH and DELETE on /projects/{project_id}/facts/{fact_id}. Any other method gets a plain 405.
404 is deliberately vague: it reads the same for “doesn’t exist” and “not yours”, so a key can’t discover which ids exist in your workspace.

Look up a type

The type URI is relative to the API host and resolves to a description of the problem. The lookup is public and needs no key:

Examples

GET /projects/{project_id}/visibility?from=2025-01-01&to=2026-06-30
GET /projects/{project_id}/fact-checks?verdict=wrong
POST /projects/{project_id}/facts with { "statements": [] }

Handle errors in code

Branch on the code at the end of type. Retry only 429 and 500; everything else needs a change on your side. Before you retry a write, read Retry writes safely.

Retry writes safely

Every GET is safe to retry. The facts writes need a little care when a request times out or fails with a 5xx, because you can’t tell whether the change was made:
  • POST /projects/{project_id}/facts: send an Idempotency-Key header with a unique value of 8 to 255 characters, such as a UUID, and reuse it when you retry. If the first request succeeded, the retry returns the same facts with 200 and an Idempotent-Replayed: true header instead of adding them again. Keys are per workspace. A key reused for a different request (another body, brand or API key), or while the first request is still running, gets 409 conflict. Quotable remembers a key for 24 hours, and only when the request succeeded, so after an error response you can fix the cause and retry with the same key. Without the header, a retry of a request that went through gets 409 conflict, because the facts are already in the list.
  • PATCH /projects/{project_id}/facts/{fact_id}: the body sets the fact’s wording or switch to a value, so sending it again gives the same result.
  • DELETE /projects/{project_id}/facts/{fact_id}: removing a fact that’s already removed returns it unchanged.
Log requestId with every failure. When you contact support, the request id lets us find the exact request in seconds.

Next steps

Caching and request IDs

Send your own request ids and use ETags to save bandwidth.

Rate limits

Back off correctly on 429.
Last modified on November 19, 2026