Errors

RetainDB API error shape, status codes, and debugging practices.

Applies to: RetainDB API v1

RetainDB errors use a consistent envelope.

json

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing API key or Authorization header"
  },
  "trace_id": "trc_..."
}

Common status codes

Status	Meaning	What to do
`400`	Invalid request body	Check required fields and field names
`401`	Missing or invalid API key	Send `Authorization: Bearer $RETAINDB_API_KEY`
`403`	Key is valid but not allowed	Check project, key scope, and account state
`404`	Resource not found	Check IDs such as memory or handoff id
`409`	Idempotency conflict	Reuse the same body for the same key or generate a new key
`429`	Rate or usage limit	Back off and inspect usage
`500`	Server or provider error	Retry safely and include `trace_id` in support reports

Log the trace_id.
Confirm the request is server-side.
Confirm the API key belongs to the expected environment.
Confirm project, user_id, session_id, agent_id, and task_id match across write and read.
Retry idempotent operations with the same Idempotency-Key.

Was this page helpful?

Your feedback helps us prioritize docs improvements weekly.