Errors - Medera

Errors follow a consistent JSON shape:

{
  "error": {
    "code": "rls_denied",
    "message": "Access to resource is denied by tenant policy.",
    "request_id": "req_abc123"
  }
}

Status codes

Code	Meaning
400	Invalid request — see `error.code`
401	Unauthenticated — token / API key missing or expired
403	Forbidden — scope or RLS denial
404	Not found (or RLS-hidden)
409	Conflict — `lock_version` mismatch, duplicate idempotency key
422	Validation failure
429	Rate limit
500	Internal error
503	Service unavailable — see `/health/dependencies`

Code	When
`invalid_request`	Schema validation failure
`auth_expired`	Token expired
`scope_denied`	Token lacks required scope
`rls_denied`	Cross-tenant access attempted
`phi_consent_required`	PHI access blocked by missing consent
`crisis_handoff_required`	Crisis language detected — agent path terminated
`subscription_inactive`	Stripe subscription not active
`agent_limit_exceeded`	Tenant agent limit reached
`idempotency_conflict`	`lock_version` mismatch
`rate_limit`	RPM or burst exceeded
`circuit_open`	External service circuit breaker is open

⌘I