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
Thetype URI is relative to the API host and resolves to a description of the problem. The lookup is public and needs no key:
Examples
403 Insufficient scope
403 Insufficient scope
400 Invalid parameter: visibility range too long
400 Invalid parameter: visibility range too long
GET /projects/{project_id}/visibility?from=2025-01-01&to=2026-06-30400 Invalid parameter: unknown verdict
400 Invalid parameter: unknown verdict
GET /projects/{project_id}/fact-checks?verdict=wrong400 Invalid body: empty fact list
400 Invalid body: empty fact list
POST /projects/{project_id}/facts with { "statements": [] }404 Not found
404 Not found
Handle errors in code
Branch on the code at the end oftype. 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
EveryGET 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 anIdempotency-Keyheader 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 with200and anIdempotent-Replayed: trueheader 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, gets409 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 gets409 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.
Next steps
Caching and request IDs
Send your own request ids and use ETags to save bandwidth.
Rate limits
Back off correctly on 429.