Errors
Every status twin memory answers with, the exact message each carries, and what to do about it.
The shape of an error
An error is a JSON object with one field, detail. For most errors it is a string:
{ "detail": "X-Twin-Account is not a usable end user id: '.bad' (letters, digits, '.', '_' and '-', starting with a letter or digit, at most 41 characters)" }For a body that does not fit a route's fields, 422 carries a list, one entry per problem, with the location of
the field in loc:
{
"detail": [
{
"type": "literal_error",
"loc": ["body", "items", 0, "kind"],
"msg": "Input should be 'message', 'document' or 'note'",
"input": "image",
"ctx": { "expected": "'message', 'document' or 'note'" }
}
]
}Every response, error or not, carries an X-Request-Id header. Send your own id in X-Request-Id (letters,
digits, ., _, : and -, up to 128 characters) and it is echoed back; otherwise one is made. Quote it when you
ask for help.
Every status
400 Bad Request
The end user header is missing or unusable.
| Message | Fix |
|---|---|
X-Twin-Account is required: it names whose memory to answer from ('default' is the store the CLI builds) | Send X-Twin-Account on every /v1/memory/* request. |
X-Twin-Account is not a usable end user id: '<as sent>' (...) | Use letters, digits, ., _ and -, start with a letter or digit, and stay within the length limit. |
401 Unauthorized
| Message | Fix |
|---|---|
a bearer this service issued is required | Send Authorization: Bearer tm_… with a key from the console. The key may be wrong, revoked, or missing the Bearer prefix. |
403 Forbidden
| Message | Fix |
|---|---|
this key reads; writing takes a key that writes | add, forget, correct and versions need a read and write key. A read-only key cannot call them. |
404 Not Found
| Message | Meaning |
|---|---|
no memory for end user '<user>' yet | Nothing was ever written for this end user. On a read, treat it as empty memory. The first add creates the end user. |
no record '<id>' in this account | correct was given a record id this end user does not hold: never read yet, already retracted, or mistyped. |
Some lookups that find nothing answer 200 with an error field instead of a 404, so a model calling them as
tools gets a useful answer:
| Route | Body on a miss |
|---|---|
read | {"path", "error": "no such file", "siblings": [...]} |
history | {"subject", "error": "nothing recorded", "subjects": [...], "recorded"} |
lineage | {"of", "error": "no event, item or record by this id in this account"} |
latest with a place that matches nothing | {"found": 0, "places": [...], "why": "..."} |
versions of an unknown id | {"id", "state": "unknown", "history": []} |
413 Content Too Large
| Message | Fix |
|---|---|
body over 1000000 bytes | Send fewer items per request, or split a large document. See Limits. |
422 Unprocessable Content
A field is missing, of the wrong type, or out of bounds. The list form names the field. Common cases:
detail | Cause |
|---|---|
String should have at least 1 character at ["body", "query"] | An empty query, pattern or text. |
Value error, month must be in 1..12 at ["body", "before"] | A date that is not a real day, such as 2026-13-01. |
String should match pattern '^\d{4}-\d{2}-\d{2}' | A date that does not begin YYYY-MM-DD. |
Input should be 'message', 'document' or 'note' | An unknown item kind. |
List should have at most 500 items after validation, not <n> | Over 500 items, or over 500 ids in one list. |
And these, as plain strings:
| Message | Cause |
|---|---|
forget names nothing: give events, threads, items or sessions | A forget with every list empty. |
read needs a path; /memory/ls lists them | A read with an empty path. |
item '<id>' has no text | An item whose text is only whitespace. |
503 Service Unavailable
Retry these.
| Response | Meaning | Retry |
|---|---|---|
A detail saying the end user is rebuilt by its writer after a schema change, with Retry-After: 60 | This end user's index is being rebuilt after an upgrade. Other end users are not affected. | After Retry-After seconds. |
A plain-text 503 with no JSON body | The service has as many requests in hand as it can take. | With backoff. |
MCP errors
Over MCP, a missing or wrong key or header is refused as above, before any tool runs. Tool errors, such as an unknown tool or invalid arguments, are JSON-RPC errors. See MCP troubleshooting.
Related
- Idempotency & retries: which errors to retry.
- Limits: every bound.