Errors

This page describes the body of an error response and lists every error code and reason the Alvia API returns.

Error body

Errors use the Problem Details format (RFC 9457), with the content type application/problem+json:

{
  "type": "https://alvia.ai/docs/errors/#conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "This account has reached its plan's stored memory limit.",
  "instance": "/v1/memories",
  "code": "conflict",
  "reason": "memory_limit_reached",
  "limit": 1000,
  "used": 1000
}

Field	Required	Description
`type`	Yes	A link to the error code on this page.
`title`	Yes	A short, fixed title for the code.
`status`	Yes	The HTTP status.
`instance`	Yes	The path of your request.
`code`	Yes	The error code. Branch on it in your code; it does not change.
`detail`	No	A sentence about this occurrence. Its wording can change, so do not parse it.
`reason`	No	A more specific cause, for some codes. See Reasons.
`errors`	No	For `validation_error`: each field path with its messages.
`limit`, `used`, `resets_at`	No	For allowance and limit refusals: the limit, the amount used and the reset time.

Branch on code and reason. Show or log detail.

Error codes

Validation error

Code validation_error, status 400. The request has one or more mistakes. The errors object maps each field to its messages:

{
  "type": "https://alvia.ai/docs/errors/#validation_error",
  "title": "Validation failed",
  "status": 400,
  "instance": "/v1/memories",
  "code": "validation_error",
  "errors": {
    "content": ["Content is required"],
    "user_id": ["Received unknown parameter: 'user_id'"]
  }
}

Common causes:

A required field is missing, empty or too long.
A field the API does not know. A common case is a scope field at the top level instead of inside scope.
A value of the wrong type, or a value the API does not accept: Invalid value for '<name>'.

Nested fields are named by their path, such as scope.user_id or messages[2].role. Fix the request; do not retry it unchanged.

Invalid argument

Code invalid_argument, status 400, or 413 when the request body is larger than 5 MiB. A value is well formed but cannot be used. Check reason and detail. Causes include an occurred_at in the future on POST /v1/memories, a list cursor that is not a memory ID and a conversation too large to process. An import reports an occurred_at in the future or before 1970 as a validation_error on occurred_at.

Unauthorized

Code unauthorized, status 401. The API key is missing, malformed, expired or revoked, or its project was deleted. See When authentication fails in Authentication.

Forbidden

Code forbidden, status 403. The credential is valid but may not perform the operation. API keys do not receive this code on memory operations.

Not found

Code not_found, status 404. The resource does not exist, or it belongs to another account or project. Both cases return the same response, so an error never confirms that another account’s data exists.

On memory operations it also means:

Get, inspect and feedback: the memory is forgotten or still forming.
Context: Alvia has no context for this question right now, and a later call can return one. This is a normal result. See Get context.

Recall reports a miss as 200 with "status": "not_found".

Unsupported media type

Code unsupported_media_type, status 415. The request body is not JSON. Send Content-Type: application/json.

Conflict

Code conflict, status 409. The request conflicts with the account’s state. On memory writes, the reason is memory_limit_reached: the account holds its plan’s stored-memory limit. Forget memories or change plan. See Limits and allowances.

Rate limit exceeded

Code rate_limit_exceeded, status 429. Alvia refused the request. Check reason and the Retry-After header:

No reason. You sent requests faster than your plan’s rate limit, or Alvia is briefly protecting capacity in high demand. Wait for the seconds in Retry-After, then retry. See Rate limits.
monthly_read_quota_reached or monthly_write_quota_reached. A monthly allowance is used up. resets_at says when it resets, and Retry-After gives the seconds until then.

Internal error

Code internal_error, status 500. An unexpected error in Alvia. Retry with backoff. If it continues, report it to Alvia with the time and the instance path.

Upstream failure

Code upstream_failure, status 502 or 504. A temporary upstream error. Retry with backoff, and send a write’s same content and occurred_at. See Retries in Store memories.

Capacity exceeded

Code capacity_exceeded, status 503. Alvia is briefly at capacity. The response always has a Retry-After header. Wait that many seconds, then retry.

Reasons

Error	Cause
`400` `invalid_argument` `occurred_at_in_future`	`occurred_at` on `POST /v1/memories` is in the future.
`400` `invalid_argument` `occurred_at_too_old`	`occurred_at` on `POST /v1/memories` is before 1970-01-01.
`400` `invalid_argument` `message_too_large_to_process`	One imported message is too large to process. `detail` names the message.
`400` `invalid_argument` `conversation_too_large_to_process`	The imported conversation is too large for one request.
`409` `conflict` `memory_limit_reached`	The account holds its plan’s stored-memory limit.
`429` `rate_limit_exceeded` `monthly_read_quota_reached`	The monthly read allowance is used up.
`429` `rate_limit_exceeded` `monthly_write_quota_reached`	The monthly write allowance is used up.

New reasons can be added. Handle a reason you do not know by its code.

Errors in MCP tools

MCP tools report errors as tool errors, with a message instead of a code:

Error	Cause
`<name> is required.`, `Received unknown parameter: '<name>'`, `Invalid value for '<name>'` or `<field> exceeds maximum length of <N> characters.`	A wrong argument
`Rate limit exceeded for Read operations. Retry in <n>s.` (or `Write`)	A rate limit
`The search service is temporarily unavailable. Retry in <n>s.`	Alvia is briefly at capacity; wait, then retry
The allowance’s message, the amount used and the reset time	A used-up allowance
The limit’s message, the amount stored and `Forget memories to make room.`	The stored-memory limit
`The tool failed to complete the request.`	An unexpected failure

forget_memory and give_memory_feedback report a missing memory as "status": "not_found" in their result, not as an error. See Alvia MCP server tools.