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

# Caching and request IDs

> Use ETag and If-None-Match to skip unchanged responses, and X-Request-Id to correlate your logs with ours.

## Response headers

Every successful response carries these headers:

| Header | Value | Purpose |
| - | - | - |
| `Cache-Control` | `private, no-store` | Responses hold your workspace's data. Shared caches and proxies must not store them. |
| `ETag` | A strong validator, for example `"q3D2x8kVb1mN0pR7sT9uW4yZ6aC"` | A hash of the exact response body. Send it back as `If-None-Match`. |
| `X-Request-Id` | Your id, or one we generate | Correlates the request across your logs and ours. |
| `X-Api-Version` | `2026-09-18` | The contract date this response follows. See [Versioning](https://docs.usequotable.com/api-reference/versioning.md). |
| `X-RateLimit-*` | Numbers | Your remaining allowance. See [Rate limits](https://docs.usequotable.com/api-reference/rate-limits.md). |

Error responses carry `Cache-Control`, `Content-Type: application/problem+json` and `X-Request-Id`, but no `ETag`.

## Conditional requests with ETags

The `ETag` changes whenever the response body changes, and only then. To check whether data changed without downloading it again, send the last `ETag` you received in `If-None-Match`:

```bash cURL theme={"system"}
curl -i "https://app.usequotable.com/api/v1/projects/$PROJECT_ID/visibility" \
  -H "Authorization: Bearer $QUOTABLE_API_KEY" \
  -H 'If-None-Match: "q3D2x8kVb1mN0pR7sT9uW4yZ6aC"'
```

```javascript JavaScript theme={"system"}
const cache = new Map(); // url -> { etag, body }

export async function getWithEtag(url) {
  const cached = cache.get(url);
  const res = await fetch(url, {
    headers: {
      Authorization: `Bearer ${process.env.QUOTABLE_API_KEY}`,
      ...(cached ? { "If-None-Match": cached.etag } : {}),
    },
  });
  if (res.status === 304) return cached.body; // unchanged
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  const body = await res.json();
  cache.set(url, { etag: res.headers.get("etag"), body });
  return body;
}
```

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

cache = {}  # url -> (etag, body)

def get_with_etag(url):
    headers = {"Authorization": f"Bearer {os.environ['QUOTABLE_API_KEY']}"}
    if url in cache:
        headers["If-None-Match"] = cache[url][0]
    res = requests.get(url, headers=headers, timeout=30)
    if res.status_code == 304:
        return cache[url][1]  # unchanged
    res.raise_for_status()
    body = res.json()
    cache[url] = (res.headers["ETag"], body)
    return body
```

If the body is unchanged, you get `304 Not Modified` with no body, along with the same `ETag`, `X-Request-Id`, `X-Api-Version` and `X-RateLimit-*` headers. Otherwise you get a normal `200` with the new body and a new `ETag`.

* `If-None-Match` accepts a comma-separated list of ETags, weak (`W/"…"`) or strong, and `*`.
* The ETag is a hash of the body alone. Store one ETag per URL, including its query string, and send it only with that URL.
* A `304` still counts toward your [rate limit](https://docs.usequotable.com/api-reference/rate-limits.md). It saves bandwidth and parsing, not requests.

> [!TIP]
>
> `Cache-Control: no-store` stops intermediaries such as CDNs and proxies from keeping a copy. Your own application can still keep the last body and its `ETag` in memory or a database to revalidate later, as in the example above.

## Request IDs

Every response, success or error, carries an `X-Request-Id` header. Error bodies repeat it as `instance: "urn:request:<id>"`.

* **Send your own.** If your request includes an `X-Request-Id` of 1 to 128 characters using only letters, digits, `.`, `_`, `:` or `-`, the response echoes it back. Use your trace or span id to follow a request end to end.
* **Or let us assign one.** If you don't send one, or yours doesn't match that format, Quotable assigns a fresh id, usually a UUID.

```bash theme={"system"}
curl -i https://app.usequotable.com/api/v1/me \
  -H "Authorization: Bearer $QUOTABLE_API_KEY" \
  -H "X-Request-Id: nightly-export-2026-10-01.42"
```

```http theme={"system"}
HTTP/2 200
x-request-id: nightly-export-2026-10-01.42
```

> [!NOTE]
>
> Log the `X-Request-Id` of every failed request. When you contact support, include it: it lets us find the exact request.

## Next steps

> [card] [Versioning](https://docs.usequotable.com/api-reference/versioning.md)
>
> What X-Api-Version means and which changes count as breaking.

> [card] [Errors](https://docs.usequotable.com/api-reference/errors.md)
>
> Every problem type the API returns.


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