# Caching, limits and errors

How long answers are cached, how many requests you can make, and what an error looks like.

Canonical: https://interlinea.aeterna-institute.org/docs/limits

## Caching

Answers carry `Cache-Control`, so Vercel's CDN, and your own cache, can serve repeats. Catalogue and text answers keep for a day at the CDN. Stored analyses, notes, word lookups and any `include=` answer keep for an hour, since they grow as readers open sections.

| Endpoint | Cached as |
|---|---|
| [`/api/v1/text`](https://interlinea.aeterna-institute.org/docs/api/text.md) | catalogue, or live with `include` |
| [`/api/v1/analysis`](https://interlinea.aeterna-institute.org/docs/api/analysis.md) | live |
| [`/api/v1/context`](https://interlinea.aeterna-institute.org/docs/api/context.md) | live |
| [`/api/v1/words`](https://interlinea.aeterna-institute.org/docs/api/words.md) | live |
| [`/api/v1/search`](https://interlinea.aeterna-institute.org/docs/api/search.md) | catalogue |
| [`/api/v1/library/{lang}/{author}`](https://interlinea.aeterna-institute.org/docs/api/author.md) | catalogue |
| [`/api/v1/library/{lang}/{author}/{work}`](https://interlinea.aeterna-institute.org/docs/api/work.md) | catalogue |
| [`/api/v1/library/{lang}/{author}/{work}/{ref}`](https://interlinea.aeterna-institute.org/docs/api/section.md) | catalogue, or live with `include` |
| [`/api/v1/passages`](https://interlinea.aeterna-institute.org/docs/api/passages.md) | catalogue |
| [`/api/v1/passages/{lang}/{slug}`](https://interlinea.aeterna-institute.org/docs/api/passage.md) | catalogue, or live with `include` |
| [`/api/v1`](https://interlinea.aeterna-institute.org/docs/api/index.md) | catalogue |
| [`/api/v1/openapi.json`](https://interlinea.aeterna-institute.org/docs/api/openapi.md) | catalogue |

| Class | Cache-Control |
|---|---|
| catalogue | `public, max-age=3600, s-maxage=86400, stale-while-revalidate=604800` |
| live | `public, max-age=300, s-maxage=3600, stale-while-revalidate=86400` |

Errors are cached for a few minutes, as the examples below show, and a `500` never is. MCP calls are POST, so the CDN doesn't cache them, but the reads behind them are cached.

## Rate limits

Please keep to 120 requests a minute from one address, across the API and the MCP server together. Past that, requests get `429 Too Many Requests` for the rest of the minute. Because answers are cached, a script that reads a work section by section stays well under it. If you need more, [write to us](https://interlinea.aeterna-institute.org/contact).

## Errors

An error is JSON with a stable `code` and a `message` that says what to pass instead:

| Field | Type | Description |
|---|---|---|
| `error` | object |  |
| `error.code` | string | One of `bad-request`, `not-found`, `server-error`. |
| `error.message` | string |  |

| Status | code | When |
|---|---|---|
| `400` | `bad-request` | A parameter is missing or invalid, or the reference isn't a text. |
| `404` | `not-found` | The author, work, section or passage isn't in the library. |
| `429` |  | Too many requests from one address. Wait a minute. |
| `500` | `server-error` | Something went wrong on our side. Try again in a minute. |

### A bad parameter

```sh
curl "https://interlinea.aeterna-institute.org/api/v1/search?q=homer&limit=500"
```

Response (400 Bad Request):

```json
{
  "error": {
    "code": "bad-request",
    "message": "limit: Too big: expected number to be <=100"
  }
}
```

### Not in the library

```sh
curl "https://interlinea.aeterna-institute.org/api/v1/library/latin/nobody"
```

Response (404 Not Found):

```json
{
  "error": {
    "code": "not-found",
    "message": "nobody isn't in the library."
  }
}
```

### Over MCP

A tool never answers with a protocol error for a bad reference. It returns a result with `isError: true` and the same kind of message, so the model can read it and try again. See [MCP errors](https://interlinea.aeterna-institute.org/docs/mcp.md#errors).

---

Previous: [Analyses and context](https://interlinea.aeterna-institute.org/docs/analyses.md)
Next: [Changelog](https://interlinea.aeterna-institute.org/docs/changelog.md)