Error codes

Every failure is a problem+json body with a stable type URI. This page enumerates the ones you'll actually see.

type slug	HTTP	Meaning	Usual fix
unauthenticated	401	No valid auth header	Start a session with a device key, then send the returned bearer token.
bad_header	401	Header shape wrong	Check for truncation or quoting.
scope_mismatch	403	Session bound to a different agent	Use a token minted for the target agent.
not_found	404	Row or resource absent (or not visible to you)	Confirm agent_id and IDs.
conflict	409	Unique constraint collision	Use the existing row or pick a different key.
quota_exceeded	429	postbox.send_quotas tripped	Wait for the window, or raise the tunable.
suppressed	451	Recipient is on postbox.outbound_suppressions	Remove the block after investigation.
quarantined	451	Inbound scored above injection threshold	Review body; promote manually if safe.
budget_exhausted	402	Budget hit	Raise the budget or wait.
policy_denied	403	A guardrail or governorPreflight denied the action	Adjust the policy or the request.
chain_broken	503	Audit verifier saw a bad row	Stop writes; page the on-call.
internal	500	Unhandled	File a report with the request id.

Response shape

{
  "type": "https://ujex.dev/errors/scope_mismatch",
  "title": "scope mismatch",
  "status": 403,
  "detail": "session bound to 'agent-hello' cannot act for 'agent-triage'",
  "instance": "req_01hxyz..."
}

Always log instance — it matches the request_id tag in Firebase function logs.