SESSION_ALREADY_ENDED

SessionAlreadyEnded

Session has already ended

The session has already been ended and cannot be ended again or written to. Start a new session for further activity.

PROMPT_EXTRACTION_DISABLED

PromptExtractionDisabled

A prompt reference was provided but semantic extraction is disabled for this call

A prompt_id was supplied while semantic extraction was turned off for the request. Enable extraction, or drop the prompt reference.

INVALID_REQUEST

InvalidRequest

Invalid request

The request was rejected as malformed — for example an unparseable filter or other caller-supplied value. Correct the request and resend.

INVALID_TOKEN

InvalidToken

Invalid token

The bearer token is malformed, has invalid claims, or is an ID token rather than an access token. Send a valid OIDC access token in the Authorization header.

TOKEN_EXPIRED

TokenExpired

Token has expired

The access token is past its expiry. Obtain a fresh token from your identity provider and retry.

TOKEN_VALIDATION_FAILED

TokenValidationFailed

Token validation failed

The token could not be validated against the identity provider's keys. Confirm the token was issued by the configured issuer and audience, then retry with a new token.

AUTHENTICATION_REQUIRED

AuthenticationRequired

Authentication required

No bearer token was supplied for a protected route. Include an Authorization=Bearer <access_token> header.

FORBIDDEN

Forbidden

Insufficient permissions

The token is valid but carries no AMS role, or a role below the tier this route requires (ams_ro < ams_rw < ams_admin). The response names the required tier. Grant the caller the needed role.

USER_NOT_FOUND

UserNotFound

User not found

No user exists for the user_id in the path. Create the user first, or check the identifier.

SESSION_NOT_FOUND

SessionNotFound

Session not found

No session exists for the given session_id (and user_id, when the lookup is user-scoped). Create the session first, or check the identifiers.

PROMPT_NOT_FOUND

PromptNotFound

Prompt not found

No prompt exists for the given prompt_id. Register the prompt first, or check the identifier.

PROMPT_VERSION_NOT_FOUND

PromptVersionNotFound

Prompt version not found

The requested version of the prompt does not exist. List the prompt's versions and reference an existing one.

MEMORY_BLOCK_NOT_FOUND

MemoryBlockNotFound

Memory block not found

No memory block exists for the given id (within the session, when the lookup is session-scoped). Check the block id, or note that only READY blocks are retrievable.

NOT_FOUND

NotFound

Resource not found

No route matches the requested method and path. Check the URL and HTTP method against the API reference.

USER_ALREADY_EXISTS

UserAlreadyExists

User already exists

A user with this user_id already exists. Use a different id, or fetch/update the existing user instead of creating it.

SESSION_ALREADY_EXISTS

SessionAlreadyExists

Session already exists

A session with this session_id already exists for the user. Use a different id, or continue with the existing session.

PROMPT_ALREADY_EXISTS

PromptAlreadyExists

Prompt already exists

A prompt with this prompt_id already exists. Use a different id, or update the existing prompt to create a new version.

PROMPT_ID_ARCHIVED

PromptIdArchived

Prompt has been archived and can no longer be referenced or re-created

The whole prompt id has been archived. Reference a different prompt; an archived id cannot be reused or recreated.

PROMPT_ALREADY_ARCHIVED

PromptAlreadyArchived

Prompt has already been archived

The prompt is already archived, so it cannot be archived again. No action needed.

PROMPT_VERSION_ARCHIVED

PromptVersionArchived

Prompt version has been archived and can no longer be pinned to

The referenced prompt version is archived and cannot be pinned to. Pin to a live version instead.

PROMPT_VERSION_ALREADY_ARCHIVED

PromptVersionAlreadyArchived

Prompt version has already been archived

The prompt version is already archived, so it cannot be archived again. No action needed.

PROMPT_CURRENT_VERSION_PURGE

PromptCurrentVersionPurge

Cannot purge the current version of a prompt — update it to a new version first, or purge the whole prompt instead

Purging the version currently in use is not allowed. Update the prompt to a new current version first, then purge the old one, or purge the entire prompt.

PROMPT_CURRENT_VERSION_ARCHIVE

PromptCurrentVersionArchive

Cannot archive the current version of a prompt — update it to a new version first, or archive the whole prompt instead

Archiving the version currently in use is not allowed. Update the prompt to a new current version first, then archive the old one, or archive the entire prompt.

PROMPT_ALREADY_PURGING

PromptAlreadyPurging

Prompt is currently being purged

A purge of this prompt is already in progress. Wait for it to finish before issuing another purge.

MEMORY_BLOCK_BUSY

MemoryBlockBusy

Memory block is currently being processed

The block is mid semantic-extraction and cannot be updated right now. This is transient; retry after the interval in the Retry-After header.

INVALID_REQUEST

ValidationFailed

Request validation failed

The request body or parameters failed schema validation. details.fields lists each offending field and why. Fix those fields and resend.

QUEUE_FULL

QueueFull

Memory processing queue is full

The asynchronous extraction queue is at capacity, so the block was not accepted. Back off and retry after the Retry-After header; details.queue_size and details.queue_max_size report current depth.

USER_ERROR

UserError

User operation failed

An unexpected server-side error occurred while processing the user operation. Retry; if it persists, contact support with the request_id.

SESSION_ERROR

SessionError

Session operation failed

An unexpected server-side error occurred while processing the session operation. Retry; if it persists, contact support with the request_id.

PROMPT_ERROR

PromptError

Prompt operation failed

An unexpected server-side error occurred while processing the prompt operation. Retry; if it persists, contact support with the request_id.

MEMORY_BLOCK_DELETE_FAILED

MemoryBlockDeleteFailed

Failed to delete memory block

The block could not be deleted due to a server-side error. Retry; if it persists, contact support with the request_id.

EMBEDDING_GENERATION_FAILED

EmbeddingGenerationFailed

Failed to generate embeddings for memory blocks

The embedding provider returned an error while embedding the submitted blocks. Retry; if it persists, check the embedding model configuration and provider status.

MEMORY_BLOCK_ERROR

MemoryBlockError

Memory block operation failed

An unexpected server-side error occurred while processing the memory block. Retry; if it persists, contact support with the request_id.

DATABASE_ERROR

DatabaseError

Database operation failed

A non-transient Couchbase failure that will not improve on retry. When a bucket, scope, collection, keyspace, or index is missing, details.service, details.resource, and details.name identify it; other database faults (e.g. a malformed query) carry no details and only a request_id. Check that the configured storage and FTS indexes exist.

INTERNAL_ERROR

InternalError

Internal server error

An unhandled server-side error occurred. Retry; if it persists, contact support with the request_id from the response.

MODEL_SERVICE_CONNECTION_ERROR

ModelServiceConnectionError

Unable to connect to model service

The server could not open a connection to the model provider. The body message is generic by design; the failure is identified by the X-Upstream-Service and X-Error-Class=connection_error response headers, and the underlying error is logged against the request_id. Check network egress to the provider and provider status, then retry.

MODEL_SERVICE_ERROR

ModelServiceError

Model service error

The model provider returned an unexpected error. The body message is generic; X-Upstream-Service and X-Error-Class (the provider error class) name the failure, and the detail is logged against the request_id. Retry; if it persists, check provider status.

TOKEN_VALIDATION_FAILED

AuthServiceUnavailable

Authentication service temporarily unavailable

The identity provider (OIDC discovery or JWKS endpoint) is unreachable, so the token could not be validated. This is transient and unrelated to the token itself; retry after a short delay.

DATABASE_UNAVAILABLE

DatabaseUnavailable

Database is temporarily unavailable

A transient Couchbase failure (timeout or connection loss) occurred. This is retryable; retry after a short delay. details.service is "database".

EMBEDDING_SERVICE_UNAVAILABLE

EmbeddingServiceUnavailable

Embedding service is unavailable

The embedding model failed its health check and requests are being blocked. details.service is "embedding". Retryable once the provider recovers; check the embedding model configuration and provider status.

LLM_SERVICE_UNAVAILABLE

LlmServiceUnavailable

LLM service is unavailable

The LLM (extraction) model failed its health check and requests are being blocked. details.service is "llm". Retryable once the provider recovers; check the LLM model configuration and provider status.

MODEL_SERVICE_AUTH_ERROR

ModelServiceAuthError

Model service authentication failed

The model provider rejected the configured API key. Identified by the X-Upstream-Service and X-Error-Class=authentication_error response headers. This is a server configuration issue, not the caller's; rotate or correct the provider API key.

MODEL_HEALTH_CHECK_FAILED

ModelHealthCheckFailed

Model health check failed

A pre-request model health check failed. The X-Upstream-Service=model response header marks it; no details object is returned. Retryable once the model recovers; check the model configuration and provider status.

UPSTREAM_RATE_LIMITED

UpstreamRateLimited

Model service temporarily unavailable due to upstream rate limiting

The model provider rate-limited this deployment and internal retries were exhausted. details.retry_after_seconds and details.service (embedding/llm/unknown) accompany it, mirrored by the Retry-After and X-Error-Class=rate_limit_exhausted headers. Back off and retry after Retry-After.

UPSTREAM_QUOTA_EXHAUSTED

UpstreamQuotaExhausted

Model provider account quota exhausted — retrying will not help

The model provider account is out of quota or credits. details.service names the affected model and details.retry_after_seconds is 0; the X-Error-Class=quota_exhausted header marks it and no Retry-After is sent. This is permanent until resolved; top up credits or rotate the API key.

MEMORY_PRESSURE

MemoryPressure

Server is under memory pressure

The server is shedding load because memory usage crossed its threshold. No details object is returned; the Retry-After and X-Memory-Usage-Percent response headers carry the specifics. Back off and retry after Retry-After.

MODEL_SERVICE_TIMEOUT

ModelServiceTimeout

Model service request timed out

The model provider did not respond within the timeout. Identified by the X-Upstream-Service and X-Error-Class=timeout response headers. Retry; if it persists, check provider status and latency.