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

error.code

string

required

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

error.message

string

required

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

error.type

string

required

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

error.provider

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.

error.request_id

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.

​Standard error envelope

​Error fields

​Error code reference

​Handling errors with curl

Standard error envelope

Error fields

Error code reference

Handling errors with curl