> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usequotable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Every API error is an RFC 9457 problem document with a stable type code, the HTTP status and the request id to quote to support.

When a request fails, the API answers with an HTTP error status and a JSON **problem document** ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)). Every error has the same shape, so one handler covers them all.

## Shape

```http theme={"system"}
HTTP/2 400
content-type: application/problem+json; charset=utf-8
cache-control: private, no-store
x-request-id: 9a1c3e5f-7b2d-4f6a-8c0e-1d3f5b7a9c2e
```

```json theme={"system"}
{
  "type": "/api/v1/problems/invalid_parameter",
  "title": "Invalid parameter",
  "status": 400,
  "detail": "limit: Too big: expected number to be <=100",
  "instance": "urn:request:9a1c3e5f-7b2d-4f6a-8c0e-1d3f5b7a9c2e",
  "errors": [
    { "parameter": "limit", "message": "Too big: expected number to be <=100" }
  ]
}
```

| Member | Always present | Meaning |
| - | - | - |
| `type` | Yes | A URI identifying the problem. The last path segment is the stable **code**. Branch on this, never on `title` or `detail`. |
| `title` | Yes | A short, human-readable summary of the type. |
| `status` | Yes | The HTTP status code, repeated for convenience. |
| `detail` | No | A human-readable explanation of this occurrence. Wording can change; don't parse it. |
| `instance` | Yes | `urn:request:<id>`, the same id as the `X-Request-Id` header. |
| `scope` | `insufficient_scope` only | The scope the endpoint requires. |
| `errors` | `invalid_parameter`, `invalid_body`, and `invalid_cursor` when the cursor is too long | For a query or path, a list of `{ "parameter", "message" }`, one per invalid parameter. For a request body, a list of `{ "field", "message" }`, one per invalid field. |

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

## Problem types

| Status | Code | When it happens | What to do |
| - | - | - | - |
| `400` | `invalid_parameter` | A query parameter failed validation: `limit` out of range, an unknown `status`, a malformed date, a visibility range over 366 days or with `from` after `to`. | Fix the parameters listed in `errors`. Don't retry unchanged. |
| `400` | `invalid_body` | The JSON body of a facts write is missing, malformed or fails validation. | Fix the fields listed in `errors`. Don't retry unchanged. |
| `400` | `invalid_cursor` | The `cursor` isn't one this API issued, or was changed. | Restart from the first page without `cursor`. |
| `401` | `unauthorized` | No key, a malformed key, or a key that is unknown, revoked, expired, or whose creator lost access. `detail` says which. | Check the key. See [Authentication](https://docs.usequotable.com/api-reference/authentication.md). Don't retry unchanged. |
| `402` | `plan_limit` | A facts write would take the brand past its plan's active facts. Nothing was changed. | Switch off or remove facts, or upgrade. See [Plans and limits](https://docs.usequotable.com/workspace/plans-and-limits.md). |
| `403` | `insufficient_scope` | The key is valid but lacks the endpoint's scope. `scope` names it. | Create a key with that scope. |
| `403` | `forbidden` | The key may not make this change, for example because the member who created it can no longer edit the brand. | Have a current owner or integration admin create a replacement key. |
| `403` | `unavailable` | The feature behind the endpoint isn't enabled for this workspace. Returned by the fact-check endpoints. | Check your plan, or contact support. |
| `404` | `not_found` | The id doesn't exist in this workspace, is outside the key's brand allowlist, or isn't a valid UUID. Also returned by demand terms when your plan doesn't include Prompt Volumes. | Check the id and the key's `project_ids` in `/me`. |
| `409` | `conflict` | The write conflicts with what is stored: a fact that's already in the list, or an `Idempotency-Key` already used for a different request or still being processed. | Read the current facts, or use a new idempotency key for a new request. |
| `429` | `rate_limited` | The key used its 300 requests for the current window, or too many failed authentications came from your network. | Wait `Retry-After` seconds, then retry. See [Rate limits](https://docs.usequotable.com/api-reference/rate-limits.md). |
| `500` | `internal` | Something failed on our side. | Retry with backoff. If it persists, contact support with the `instance` id. |

The catalog has one more code, `method_not_allowed` (`405`), which the [MCP endpoint](https://docs.usequotable.com/mcp-server/overview.md) 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`.

> [!NOTE]
>
> `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:

```bash theme={"system"}
curl https://app.usequotable.com/api/v1/problems/rate_limited
```

```json theme={"system"}
{
  "type": "/api/v1/problems/rate_limited",
  "status": 429,
  "title": "Rate limited",
  "description": "The key exhausted its request allowance for the current window. Wait `Retry-After` seconds; the `X-RateLimit-*` headers describe the window."
}
```

## Examples

> [accordion] 401 Unauthorized: revoked key
>
> ```http theme={"system"}
> HTTP/2 401
> content-type: application/problem+json; charset=utf-8
> www-authenticate: Bearer realm="api"
> ```
>
> ```json theme={"system"}
> {
>   "type": "/api/v1/problems/unauthorized",
>   "title": "Unauthorized",
>   "status": 401,
>   "detail": "This API key was revoked.",
>   "instance": "urn:request:5e7a9c1b-3d5f-4a7c-9e1b-3d5f7a9c1e3b"
> }
> ```

> [accordion] 403 Insufficient scope
>
> ```json theme={"system"}
> {
>   "type": "/api/v1/problems/insufficient_scope",
>   "title": "Insufficient scope",
>   "status": 403,
>   "detail": "This endpoint requires the read:demand scope.",
>   "instance": "urn:request:1f3b5d7e-9a2c-4e6f-8b0d-2f4a6c8e0b1d",
>   "scope": "read:demand"
> }
> ```

> [accordion] 400 Invalid parameter: visibility range too long
>
> `GET /projects/{project_id}/visibility?from=2025-01-01&to=2026-06-30`
>
> ```json theme={"system"}
> {
>   "type": "/api/v1/problems/invalid_parameter",
>   "title": "Invalid parameter",
>   "status": 400,
>   "detail": "The range may span at most 366 days.",
>   "instance": "urn:request:3c5e7a9b-1d3f-4b5c-8e7a-9b1d3f5c7e9a",
>   "errors": [
>     { "parameter": "from,to", "message": "The range may span at most 366 days." }
>   ]
> }
> ```

> [accordion] 400 Invalid parameter: unknown verdict
>
> `GET /projects/{project_id}/fact-checks?verdict=wrong`
>
> ```json theme={"system"}
> {
>   "type": "/api/v1/problems/invalid_parameter",
>   "title": "Invalid parameter",
>   "status": 400,
>   "detail": "verdict: Invalid option: expected one of \"supported\"|\"contradicted\"",
>   "instance": "urn:request:8d0f2b4c-6e8a-4c0d-9f2b-4c6e8a0d2f4b",
>   "errors": [
>     {
>       "parameter": "verdict",
>       "message": "Invalid option: expected one of \"supported\"|\"contradicted\""
>     }
>   ]
> }
> ```

> [accordion] 400 Invalid body: empty fact list
>
> `POST /projects/{project_id}/facts` with `{ "statements": [] }`
>
> ```json theme={"system"}
> {
>   "type": "/api/v1/problems/invalid_body",
>   "title": "Invalid body",
>   "status": 400,
>   "detail": "statements: Too small: expected array to have >=1 items",
>   "instance": "urn:request:2a4c6e8b-0d2f-4a6c-8e0b-2d4f6a8c0e2b",
>   "errors": [
>     { "field": "statements", "message": "Too small: expected array to have >=1 items" }
>   ]
> }
> ```

> [accordion] 404 Not found
>
> ```json theme={"system"}
> {
>   "type": "/api/v1/problems/not_found",
>   "title": "Not found",
>   "status": 404,
>   "instance": "urn:request:4b6d8f0a-2c4e-4a6b-8d0f-2a4c6e8b0d2f"
> }
> ```

## 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).

```javascript JavaScript theme={"system"}
export class QuotableError extends Error {
  constructor(problem, status) {
    super(problem.detail ?? problem.title ?? `HTTP ${status}`);
    this.status = status;
    this.code = problem.type?.split("/").pop() ?? "unknown";
    this.requestId = problem.instance?.replace("urn:request:", "");
    this.problem = problem;
  }
}

export async function call(url, init = {}, attempt = 0) {
  const res = await fetch(url, {
    ...init,
    headers: { ...init.headers, Authorization: `Bearer ${process.env.QUOTABLE_API_KEY}` },
  });
  if (res.ok) return res.json();

  const problem = res.headers.get("content-type")?.startsWith("application/problem+json")
    ? await res.json()
    : { title: res.statusText };
  const error = new QuotableError(problem, res.status);

  const retryable = error.code === "rate_limited" || res.status >= 500;
  if (retryable && attempt < 3) {
    const wait = Number(res.headers.get("retry-after")) || 2 ** attempt;
    await new Promise((r) => setTimeout(r, wait * 1000));
    return call(url, init, attempt + 1);
  }
  throw error;
}
```

```python Python theme={"system"}
import os
import time
import requests

class QuotableError(Exception):
    def __init__(self, problem, status):
        super().__init__(problem.get("detail") or problem.get("title") or f"HTTP {status}")
        self.status = status
        self.code = (problem.get("type") or "").rsplit("/", 1)[-1] or "unknown"
        self.request_id = (problem.get("instance") or "").removeprefix("urn:request:")
        self.problem = problem

def call(url, params=None, attempt=0):
    res = requests.get(
        url,
        params=params,
        headers={"Authorization": f"Bearer {os.environ['QUOTABLE_API_KEY']}"},
        timeout=30,
    )
    if res.ok:
        return res.json()

    is_problem = res.headers.get("Content-Type", "").startswith("application/problem+json")
    error = QuotableError(res.json() if is_problem else {"title": res.reason}, res.status_code)

    if (error.code == "rate_limited" or res.status_code >= 500) and attempt < 3:
        time.sleep(int(res.headers.get("Retry-After") or 2 ** attempt))
        return call(url, params, attempt + 1)
    raise error
```

## 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.

```bash theme={"system"}
curl -X POST "https://app.usequotable.com/api/v1/projects/$PROJECT_ID/facts" \
  -H "Authorization: Bearer $QUOTABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"statements": ["Acme Analytics has a free plan for up to 3 users."]}'
```

> [!TIP]
>
> Log `requestId` with every failure. When you contact support, the request id lets us find the exact request in seconds.

## Next steps

> [card] [Caching and request IDs](https://docs.usequotable.com/api-reference/caching-and-request-ids.md)
>
> Send your own request ids and use ETags to save bandwidth.

> [card] [Rate limits](https://docs.usequotable.com/api-reference/rate-limits.md)
>
> Back off correctly on 429.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.