Use structured error codes in GraphQL
Context
We need to decide how to handle error messages across the GraphQL API and iOS client. The backend can either return user-facing error messages in English, or return machine-readable codes and let clients handle localization.
Decision
Return structured error codes via GraphQL error extensions. iOS parses the codes and provides localized messages.
{
"errors": [{
"message": "AUTHENTICATION_REQUIRED",
"extensions": { "code": "AUTHENTICATION_REQUIRED" }
}]
}
case "AUTHENTICATION_REQUIRED":
return .authenticationRequired
// AuthError.errorDescription provides localized strings
Structured codes are for domain errors that users can understand and act on — validation failures, authorization errors, expected failure modes. Infrastructure errors (sqlx, UUID parsing) propagate via ? as generic internal errors.
Consequences
The API stays language-agnostic — no English strings hardcoded in resolvers. iOS follows platform conventions with LocalizedError and Localizable.strings. Tests verify specific error codes rather than matching on English text.
The cost is coordination: new error codes need both backend and iOS updates, and each code needs client-side handling.