--- title: The Agent Memory API Errors description: An explanation of error messages generated by the Agent Memory API. pubDate: 2026-10-19T14:21:08.937Z meta: component: title: Couchbase Agent Memory version: "1.1" topic_type: reference antora: editUrl: https://github.com/couchbaselabs/docs-agentmemory/edit/release/1.1/modules/api-guide/pages/self-managed/api-errors.adoc xref: xref:agent-mem:api-guide:self-managed/api-errors.adoc[] --- [Consult the llms.txt file for a full list of contents](/llms.txt) [View original HTML](/agent-mem/current/api-guide/self-managed/api-errors.html) # The Agent Memory API Errors > An explanation of error messages generated by the Agent Memory API. This page is for self-managed Agent Memory. API errors occur when a request fails to complete, typically returning standardized HTTP status codes that indicate the type and cause of the failure. ## [](#agent-memory-api-errors)Agent Memory API Error Messages ### HTTP Status 400 Bad request. | Code | Name | Description | HTTP Status | | ---------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | 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. | 400 | | 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. | 400 | | 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. | 400 | ### HTTP Status 401 Unauthorized. | Code | Name | Description | HTTP Status | | ------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | 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. | 401 | | TOKEN\_EXPIRED | TokenExpired | Token has expired The access token is past its expiry. Obtain a fresh token from your identity provider and retry. | 401 | | 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. | 401 | | AUTHENTICATION\_REQUIRED | AuthenticationRequired | Authentication required No bearer token was supplied for a protected route. Include an Authorization=Bearer header. | 401 | ### HTTP Status 403 Forbidden. | Code | Name | Description | HTTP Status | | --------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | 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. | 403 | ### HTTP Status 404 Not found. | Code | Name | Description | HTTP Status | | --------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | 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. | 404 | | 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. | 404 | | PROMPT\_NOT\_FOUND | PromptNotFound | Prompt not found No prompt exists for the given prompt\_id. Register the prompt first, or check the identifier. | 404 | | 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. | 404 | | 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. | 404 | | NOT\_FOUND | NotFound | Resource not found No route matches the requested method and path. Check the URL and HTTP method against the API reference. | 404 | ### HTTP Status 409 Conflict. | Code | Name | Description | HTTP Status | | ---------------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | 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. | 409 | | 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. | 409 | | 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. | 409 | | 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. | 409 | | PROMPT\_ALREADY\_ARCHIVED | PromptAlreadyArchived | Prompt has already been archived The prompt is already archived, so it cannot be archived again. No action needed. | 409 | | 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. | 409 | | 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. | 409 | | 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. | 409 | | 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. | 409 | | 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. | 409 | | 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. | 409 | ### HTTP Status 422 Unprocessable content. | Code | Name | Description | HTTP Status | | ---------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | | 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. | 422 | ### HTTP Status 429 Too many requests. | Code | Name | Description | HTTP Status | | ----------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | 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. | 429 | ### HTTP Status 500 Internal server errors. | Code | Name | Description | HTTP Status | | ----------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | | 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. | 500 | | 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. | 500 | | 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. | 500 | | 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. | 500 | | 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. | 500 | | 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. | 500 | | 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. | 500 | | 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. | 500 | ### HTTP Status 502 Bad gateway. | Code | Name | Description | HTTP Status | | --------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | 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. | 502 | | 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. | 502 | ### HTTP Status 503 Service unavailable. | Code | Name | Description | HTTP 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. | 503 | | 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". | 503 | | 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. | 503 | | 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. | 503 | | 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. | 503 | | 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. | 503 | | 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. | 503 | | 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. | 503 | | 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. | 503 | ### HTTP Status 504 Gateway timeout. | Code | Name | Description | HTTP Status | | ----------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | 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. | 504 | ## [](#see-also)See Also * For more information about the Agent Memory API, see [Agent Memory API for Self-Managed Deployments](api-intro.md). * For a full reference guide, see [Agent Memory API Reference](../../agent-memory-api-reference/rest-api.md). * To make an API call, see [Make an API Call with the Agent Memory API](api-use.md).