OMP API error codes and HTTP status mapping

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

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

Error fields

string

required

Machine-readable error identifier. Use this field to branch your error-handling logic. Values are enumerated in the table below.

string

required

Human-readable description of what went wrong. Suitable for logging, but do not parse it programmatically — use code instead.

string

required

Broad category of the error. One of auth, not_found, invalid, rate_limited, or provider_error.

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.

string

Opaque identifier for this specific request. Include this value when reporting issues or correlating errors with server-side access logs.

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

curl -s -X GET http://localhost:8080/memories/mem_notexist | jq .error.code
# "not_found"

You can also inspect the full envelope:

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"
# }

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.

Overview

Endpoints

OMP API error codes and HTTP status mapping

Standard error envelope

Error fields

Error code reference

Handling errors with curl

​Standard error envelope

​Error fields

​Error code reference

​Handling errors with curl

Standard error envelope

Error fields

Error code reference

Handling errors with curl