Skip to main content

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.

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

codeHTTP statustypeMeaning
unauthorized401authMissing or invalid API key
scope_denied403authRequest lacks the required scope permission
not_found404not_foundThe requested resource does not exist
invalid_request400invalidMalformed body or invalid query parameters
rate_limited429rate_limitedProvider rate limit exceeded
unsupported_capability400invalidThe requested verb is not supported by this provider
provider_error502provider_errorThe upstream provider returned an unexpected error
payload_too_large413invalidRequest 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.