Errors Mobile Clients Can Act On

A mobile app needs to decide what to do with an error: retry, re-authenticate, show a field error, ask the user to update, or give up. Use RFC 9457 problem details with a stable type/code the app branches on, field-level errors for forms, a retryable hint or Retry-After, and a request ID users can quote to support. Keep user-facing text localizable: either the server localizes via Accept-Language or the app maps codes to its own strings (safer for old versions, which keep their mapping).

Error → client action

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
X-Request-Id: req_7Hq2…

{
  "type": "https://api.example.com/problems/validation",
  "title": "Some fields are invalid",
  "status": 422,
  "errors": [{"pointer": "/delivery/postcode", "code": "postcode_invalid"}],
  "request_id": "req_7Hq2…"
}

when (problem.type.substringAfterLast('/')) {
    "validation" -> showFieldErrors(problem.errors)
    "upgrade-required" -> navigateToUpgrade()
    "rate-limited" -> scheduleRetry(problem.retryAfter)
    else -> showGeneric(problem.requestId)      // unknown codes: safe fallback
}

Common pitfalls

• Apps parsing English error messages.
• Changing error codes between releases.
• 200 OK with an error body.

Key points

• Stable codes, not messages
• Field-level errors + request IDs
• Unknown code → safe fallback

Further reading: RFC 9457: Problem Details for HTTP APIs