Skip to main content

​
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

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

​
Error codes

Current public and semi-public API surfaces emit the following codes.
CodeMeaningTypical cause
AUTH_001UnauthorizedMissing or invalid API key
AUTH_002Workspace not readyDashboard token is valid, but the selected workspace has not finished provisioning
AUTH_003Workspace requiredDashboard token is valid, but no workspace is active
AUTH_403Workspace auth requiredRoute expected workspace context but none was resolved
UAT_001Cross-agent auth failedMissing or invalid agent_sk_... key or uui_... token
UAT_002Write not permittedAgent grant is read-only and attempted a universal write
UUI_001Invalid UUI tokenMissing, revoked, or unknown Memory Passport token
UUI_404Universal user not foundDelete request targeted a user that no longer exists
GNT_404Permission grant not foundRevoke request referenced a grant outside this user scope
AGN_404Global agent not foundConsent or public agent lookup used an invalid agent id
REQ_422Validation errorMissing required fields, wrong types, or empty content
MEM_404Memory not foundMemory id does not exist or is out of scope
JOB_404Job not foundExtraction job id does not exist or is not visible to the tenant
PRX_403Proxy user blockedEnd user is blocked from new writes
PRX_404Proxy user not foundTenant-scoped user does not exist
PRX_500Proxy user resolution failedProxy-user service unavailable or failed
TEN_400Tenant request errorInvalid cursor or missing webhook configuration
TEN_404Tenant budget not foundTenant budget row missing
EMB_503Embedding unavailableEmbedding dependency failed
SRV_500Internal server errorUnhandled backend error
SRV_503Service unavailableDependency fallback or temporary infrastructure issue
HTTP_ERRORGeneric HTTP exceptionFramework-level HTTP exception
Current releases do not emit VAL_* codes. Validation failures are returned as REQ_422.

​
Consent and universal memory note

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.