> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memoryo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Error response format, status codes, and current public error codes.

## Error response format

MemoryOS returns structured JSON errors:

```json theme={null}
{
  "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`   | Workspace auth required      | Route expected workspace context but none was resolved                             |
| `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                   |
| `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`.

## 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.