Errors

Every error response from the API follows RFC 9457 Problem Details for HTTP APIs. The code field is the stable contract — the mobile client switches on it to drive UX.

Body shape

Content-Type is application/problem+json. The optional meta object (an RFC 9457 extension member) appears only on errors that carry machine-readable context the client must act on — currently ACCOUNT_PENDING_DELETION, which sets meta.deletedAt and meta.deletionScheduledAt.

Error catalog

Every code in the codebase appears in this table. When an endpoint can return non-obvious codes, its reference page lists them in an Error responses section.

How errors map server-side

  • A controller or service throws AppError(code) from @swappr/shared.
  • The Express error middleware converts it to the Problem Details JSON above.
  • Anything that ISN’T an AppError (library exceptions, runtime crashes) maps to INTERNAL_ERROR with detail: "An unexpected error occurred. Please try again later." — the underlying cause is logged server-side but never serialized to the client.