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`	payment processor 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