Skip to content
ConceptsCaching, limits and errorsDocs menu

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.

EndpointCached as
/api/v1/textcatalogue, or live with include
/api/v1/analysislive
/api/v1/contextlive
/api/v1/wordslive
/api/v1/searchcatalogue
/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/passagescatalogue
/api/v1/passages/{lang}/{slug}catalogue, or live with include
/api/v1catalogue
/api/v1/openapi.jsoncatalogue
ClassCache-Control
cataloguepublic, max-age=3600, s-maxage=86400, stale-while-revalidate=604800
livepublic, 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:

Error
NameDescription
errorobject
2 fields
error fields
codestring

One of bad-request, not-found, server-error.

messagestring
StatuscodeWhen
400bad-requestA parameter is missing or invalid, or the reference isn't a text.
404not-foundThe author, work, section or passage isn't in the library.
429Too many requests from one address. Wait a minute.
500server-errorSomething went wrong on our side. Try again in a minute.

A bad parameter

curl
curl "https://interlinea.aeterna-institute.org/api/v1/search?q=homer&limit=500"
Response400 Bad Request
{
  "error": {
    "code": "bad-request",
    "message": "limit: Too big: expected number to be <=100"
  }
}
Cache-Control: public, max-age=300

Not in the library

curl
curl "https://interlinea.aeterna-institute.org/api/v1/library/latin/nobody"
Response404 Not Found
{
  "error": {
    "code": "not-found",
    "message": "nobody isn't in the library."
  }
}
Cache-Control: public, max-age=300, s-maxage=3600

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.