Errors

Error response format

MemoryOS returns structured JSON errors:

{
  "error": "unauthorized",
  "code": "AUTH_001",
  "request_id": "420a0c64-eabd-4fc3-ad78-e043677a8359",
  "details": null
}

HTTP status codes

Status	Meaning
`200`	Request succeeded, or a non-fatal add outcome such as passthrough or quality-gate block
`400`	Invalid cursor or malformed tenant-specific request
`401`	Authentication failed
`403`	Tenant context exists but is not permitted for the request
`404`	Resource not found
`422`	Request validation failed
`429`	Rate limited
`500`	Internal server error
`503`	Dependency unavailable

Error codes

Current public and semi-public API surfaces emit the following codes.

Code	Meaning	Typical cause
`AUTH_001`	Unauthorized	Missing or invalid API key
`AUTH_002`	Workspace not ready	Dashboard token is valid, but the selected workspace has not finished provisioning
`AUTH_003`	Workspace required	Dashboard token is valid, but no workspace is active
`AUTH_403`	Request forbidden	Workspace context is missing, or the API key lacks the required `read`, `write`, `delete`, or `admin` permission
`UAT_001`	Cross-agent auth failed	Missing or invalid `agent_sk_...` key or `uui_...` token
`UAT_002`	Write not permitted	Agent grant is read-only and attempted a universal write
`UUI_001`	Invalid UUI token	Missing, revoked, or unknown Memory Passport token
`UUI_404`	Universal user not found	Delete request targeted a user that no longer exists
`GNT_404`	Permission grant not found	Revoke request referenced a grant outside this user scope
`AGN_404`	Global agent not found	Consent or public agent lookup used an invalid agent id
`REQ_422`	Validation error	Missing required fields, wrong types, or empty content
`MEM_404`	Memory not found	Memory id does not exist or is out of scope
`JOB_404`	Job not found	Extraction job id does not exist or is not visible to the tenant
`CLR_400`	Clarification cannot use this path	Conflict is tenant-review scoped or the answer cannot be applied
`CLR_404`	Clarification not found	Id, tenant, or external-user ownership did not match
`CLR_409`	Clarification no longer answerable	Clarification expired or was already resolved
`PRX_403`	Proxy user blocked	End user is blocked from new writes
`PRX_404`	Proxy user not found	Tenant-scoped user does not exist
`PRX_500`	Proxy user resolution failed	Proxy-user service unavailable or failed
`TEN_400`	Tenant request error	Invalid cursor or missing webhook configuration
`TEN_404`	Tenant budget not found	Tenant budget row missing
`EMB_503`	Embedding unavailable	Embedding dependency failed
`SRV_500`	Internal server error	Unhandled backend error
`SRV_503`	Service unavailable	Dependency fallback or temporary infrastructure issue
`HTTP_ERROR`	Generic HTTP exception	Framework-level HTTP exception

Current releases do not emit VAL_* codes. Validation failures are returned as REQ_422.

Memory Passport and Universal Memory are frozen in private beta and disabled by default. Their entry points return 404 FEATURE_404 with memory_passport_not_available unless explicitly enabled.

Some Memory Passport flows are intentionally not error-driven:

POST /v1/universal/memories/retrieve returns an empty list with permission_status: "no_grant" when a user has not granted this agent access
revocation therefore looks like a clean empty retrieve result, not a 403

This behavior is deliberate so an agent cannot use error differences to infer more than the user granted.

Memory APIs

Domain APIs

Reference

Error response format

HTTP status codes

Error codes

​Error response format

​HTTP status codes

​Error codes

​Consent and universal memory note

Error response format

HTTP status codes

Error codes

Consent and universal memory note