Error format¶

Expected application failures return a stable JSON envelope:

{
  "error": {
    "code": "IDENTITY_ASSURANCE_REQUIRED",
    "title": "Identity verification required",
    "message": "A current Face Liveness and eVerify result is required to access government documents.",
    "suggested_action": "Complete identity verification and try again.",
    "retryable": false
  }
}

Fields¶

Field	Meaning
`code`	Stable machine-readable identifier
`title`	Short citizen-friendly heading
`message`	Safe explanation without stack details
`suggested_action`	What the citizen or developer should do next
`retryable`	Whether repeating the same action may succeed

Common status classes¶

Status	Example
`400`	Capability or request not registered
`401`	Missing, invalid, expired, or signed-out session
`403`	High assurance, consent, or capability permission required
`404`	Owned resource or development-only endpoint unavailable
`409`	Invalid journey order, unavailable workflow, or missing idempotency
`413`	Upload exceeds configured size
`422`	Invalid request or unsupported document type
`429`	Capability rate limit reached
`500`	Unexpected server failure, redacted
`503`	Provider or configuration unavailable
`504`	Provider timeout

Flutter mapping¶

ApiClient converts a backend envelope into AppError. Network failures without an envelope use a local, retryable “backend unavailable” message.

UI code should display title, message, and suggestedAction; it should not branch on human-readable strings. Use code when program behavior differs.