Concepts
Caching, limits and errors
How long answers are cached, how many requests you can make, and what an error looks like.
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 | catalogue, or live with include |
/api/v1/analysis | live |
/api/v1/context | live |
/api/v1/words | live |
/api/v1/search | catalogue |
/api/v1/library/{lang}/{author} | catalogue |
/api/v1/library/{lang}/{author}/{work} | catalogue |
/api/v1/library/{lang}/{author}/{work}/{ref} | catalogue, or live with include |
/api/v1/passages | catalogue |
/api/v1/passages/{lang}/{slug} | catalogue, or live with include |
/api/v1 | catalogue |
/api/v1/openapi.json | 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.
Errors
An error is JSON with a stable code and a message that says what to pass instead:
| Name | Description | ||||
|---|---|---|---|---|---|
errorobject | 2 fields
|
| 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
curl "https://interlinea.aeterna-institute.org/api/v1/search?q=homer&limit=500"{
"error": {
"code": "bad-request",
"message": "limit: Too big: expected number to be <=100"
}
}Not in the library
curl "https://interlinea.aeterna-institute.org/api/v1/library/latin/nobody"{
"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.