Limits and errors
Only what the server sends is listed here. The page does not describe fields that no answer carries.
Rate limit
The server allows 90 requests per minute from one address by
default. It applies to the MCP address (/mcp), to /api/tool, and to the REST API. Calls made on Try count too.
Past the limit the answer is HTTP 429 with a Retry-After header in seconds, the
headers X-RateLimit-Limit and X-RateLimit-Remaining, and this body:
{
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded (90 requests per minute). Retry after 12s.",
"retryable": true
}
}The count is kept by each running copy of the server on its own, so the limit is a soft one. Wait
the time in Retry-After and try again.
When a resource is not there
A language or book that lacks a resource is not a failure. The tool answers normally, with isError: false, and the data says what is missing:
{
"available": false,
"code": "RESOURCE_NOT_AVAILABLE",
"message": "No translation questions available for this reference or language.",
"hints": ["Run list_resources to see what is available for this language."]
}The code is RESOURCE_NOT_AVAILABLE. It is sent as an answer so that an assistant
tells the translator the gap exists, and does not treat the server as down. hints says what to try next, usually list_resources.
An empty list is also an answer. notes: [], questions: [] or results: [] mean there is nothing for this passage or search, and are not errors.
These fields mark a partial answer, with isError still false:
versionsNoteonget_passage: another version of the language stood in for a missing one, and says which and why.notesErrorandavailabilityErroronget_passage_context: one part failed upstream and the rest is returned.
Errors
A real error has isError: true. Its text starts with the code, as in Error INVALID_LANGUAGE: Unknown language code: "xx", and it carries no structuredContent. On /api/tool the same code comes with an HTTP status,
shown below. Over MCP the HTTP status stays 200 and the error is in the result.
| Code | Status | Meaning |
|---|---|---|
| INVALID_REFERENCE | 400 | The reference has no chapter or verse, or is not a passage. |
| INVALID_LANGUAGE | 400 | The language code is not known. Ask list_languages. |
| MISSING_REQUIRED_PARAM | 400 | A required argument is missing. |
| INVALID_PARAMS | 400 | An argument has the wrong shape or value. |
| RESOURCE_NOT_FOUND | 404 | The thing asked for does not exist. |
| RATE_LIMITED | 429 | More than the rate limit allows. Retry after the delay. |
| UPSTREAM_DCS_ERROR | 502 | Door43 answered with an error. Marked retryable. |
| INTERNAL_ERROR | 500 | An unexpected failure on the server. |
Errors can carry hints and a retryable flag. When retryable is true, the same request can succeed later. The REST API sends errors as { "error": { code, message, retryable } }.
Response sizes
Some assistants cut long tool results, and a long answer uses up the conversation. Ask for a verse
or a short range rather than a whole book. For a passage, start with get_passage_index, which lists the helps
without their text, and open only the ones you need (see the workflow). The Try page shows the size of every answer.
Caching
Content from Door43 is cached on the server, so a repeated call is fast. Answers for a passage
(scripture, notes, key-term links and questions) carry meta.cache to say where the data
came from:
memory: kept in memory by the running copy of the server.kv: a stored copy of an earlier answer or download.r2: the stored ZIP file of the resource.network: downloaded from Door43 for this request.pack: read from a language pack.mixed: scripture only, when its parts came from different places.
The REST API also lets the network edge keep a good answer for up to an hour.