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

# OMP API error codes and HTTP status mapping

> Complete reference for every OMP error code, its HTTP status, type category, and guidance on correlating errors with server-side logs.

Every OMP endpoint returns errors in the same JSON envelope, regardless of which provider raised them. This consistency means you can write a single error-handling path in your application and it will work across all backends.

## Standard error envelope

```json theme={null}
{
  "error": {
    "code": "scope_denied",
    "message": "App lacks scope read:health",
    "type": "auth",
    "provider": "mem0",
    "request_id": "req_abc"
  }
}
```

## Error fields

<ResponseField name="error.code" type="string" required>
  Machine-readable error identifier. Use this field to branch your error-handling logic. Values are enumerated in the table below.
</ResponseField>

<ResponseField name="error.message" type="string" required>
  Human-readable description of what went wrong. Suitable for logging, but do not parse it programmatically — use `code` instead.
</ResponseField>

<ResponseField name="error.type" type="string" required>
  Broad category of the error. One of `auth`, `not_found`, `invalid`, `rate_limited`, or `provider_error`.
</ResponseField>

<ResponseField name="error.provider" type="string">
  The name of the backend that raised the error, if applicable (e.g., `postgres`, `mem0`). May be absent for client-side validation errors caught before the provider is reached.
</ResponseField>

<ResponseField name="error.request_id" type="string">
  Opaque identifier for this specific request. Include this value when reporting issues or correlating errors with server-side access logs.
</ResponseField>

## Error code reference

| `code`                   | HTTP status | `type`           | Meaning                                              |
| ------------------------ | ----------- | ---------------- | ---------------------------------------------------- |
| `unauthorized`           | 401         | `auth`           | Missing or invalid API key                           |
| `scope_denied`           | 403         | `auth`           | Request lacks the required scope permission          |
| `not_found`              | 404         | `not_found`      | The requested resource does not exist                |
| `invalid_request`        | 400         | `invalid`        | Malformed body or invalid query parameters           |
| `rate_limited`           | 429         | `rate_limited`   | Provider rate limit exceeded                         |
| `unsupported_capability` | 400         | `invalid`        | The requested verb is not supported by this provider |
| `provider_error`         | 502         | `provider_error` | The upstream provider returned an unexpected error   |
| `payload_too_large`      | 413         | `invalid`        | Request body exceeds the 1 MiB limit                 |

## Handling errors with curl

```bash theme={null}
curl -s -X GET http://localhost:8080/memories/mem_notexist | jq .error.code
# "not_found"
```

You can also inspect the full envelope:

```bash theme={null}
curl -s -X GET http://localhost:8080/memories/mem_notexist | jq .error
# {
#   "code": "not_found",
#   "message": "Memory mem_notexist not found",
#   "type": "not_found",
#   "provider": "postgres",
#   "request_id": "req_xyz"
# }
```

<Tip>
  When reporting a bug or opening a support issue, always include the `request_id` value. Server-side access logs are indexed by `request_id`, so it lets you (or your provider) locate the exact request in milliseconds.
</Tip>