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 for browsers and your own cache. Catalogue and text answers stay fresh for an hour in a browser; stored analyses, notes, word lookups and any include= answer stay fresh for five minutes, since they grow as readers open sections. The container deployment bypasses Vercel's CDN for these responses. Reads behind the API use the shared server cache, where corrections can invalidate stored results across app instances. The s-maxage values below apply to other shared caches that honor them.
| 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 |
Some error responses allow a few minutes in a browser or your own cache, as the examples below show; a 500 never does. MCP calls are POST and are not cached as HTTP responses, but the reads behind them use the shared server cache.
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. Reuse cached answers and pace section-by-section reads within that limit. If you need more, write to us.
Rules for agents and crawlers
Say who you are: send a User-Agent that names your agent or product and a way to reach you. Do not pose as a browser.
Follow robots.txt. Use the MCP server, the JSON API, the Markdown pages and the sitemaps. Do not crawl /library/search or other filtered HTML pages: /api/v1/search answers the same questions.
Keep to 120 requests a minute in total, however many addresses you send from. Do not spread requests across addresses or proxies to get past a limit.
On 429 or 503, stop and wait at least a minute before you try again. Reuse what you have already fetched; the answers change rarely.
Keep to each text's licence and credit, and to the law that applies to you and to us: copyright, data protection and computer misuse law among them.
Traffic that breaks these rules is blocked without notice. If you need more than this allows, write to us first.
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.