Errors

• global exception handling (bootstrap/app.php)
• domain controllers (auth, 2FA, registration, etc.)

​

Error contract (guaranteed)

​

Standard error shape

{
  "message": "Human readable message",
  "code": "ERROR_CODE"
}

• code Stable, machine-readable identifier. Never localized. Never changes.
• message Human-readable explanation, always localized.
• HTTP status Meaningful and intentional (see mapping below).

​

Validation error (HTTP 422)

{
  "message": "Some fields are invalid.",
  "code": "VALIDATION_FAILED",
  "errors": {
    "email": [
      "The email must be a valid email address."
    ],
    "password": [
      "The password must be at least 8 characters."
    ]
  }
}

• errors is a field → array of messages map
• messages are localized
• field names are never localized
• structure is stable across all endpoints

​

Localization of errors

1. X-App-Locale header (recommended)
2. Accept-Language
3. user.locale (authenticated requests)
4. fallback: fr

• message
• validation messages inside errors
• emails triggered during the request

​

HTTP status semantics (contract)

​

Global errors (from exception handling)

​

Validation failed

{
  "message": "Some fields are invalid.",
  "code": "VALIDATION_FAILED",
  "errors": {
    "email": ["The email must be a valid email address."]
  }
}

• Render field-level errors next to inputs
• Do not show multiple global toasts
• Do not retry automatically

​

Unauthenticated

{
  "message": "Unauthenticated.",
  "code": "UNAUTHENTICATED"
}

• Clear stored token
• Reset user state
• Redirect to login or onboarding entry point

​

Rate limited

{
  "message": "Too many attempts. Try again later.",
  "code": "RATE_LIMITED"
}

• Disable the triggering action
• Show cooldown or timer
• Never retry automatically in a loop

​

Server error (production)

{
  "message": "Something went wrong. Try again later.",
  "code": "SERVER_ERROR"
}

• Show generic error UI
• Offer a retry action
• Log client-side context if available

​

Authentication errors (anti-enumeration)

​

Invalid credentials

• unknown email
• wrong password
• account not in active state

{
  "message": "Invalid credentials.",
  "code": "INVALID_CREDENTIALS"
}

• Never indicate which field failed
• Never suggest account existence
• Optional UX: show “Forgot password?” only if implemented

​

MFA (2FA) related errors

• Restart login on MFA_CHALLENGE_GONE
• Do not retry automatically
• Lock UI on MFA_TOO_MANY_ATTEMPTS

​

Registration & onboarding errors

• Always propose the next valid step
• Never reveal internal state
• Restart flows cleanly when needed

​

Frontend best practices (mandatory)

• Always branch logic on code, never on message
• Treat 429 as a product constraint, not a bug
• Never expose backend internals to users
• Never infer account existence from errors
• Assume all messages are localized

​

Guarantees

• stable and documented error codes
• deterministic HTTP statuses
• strict anti-enumeration
• full localization coverage
• production-safe responses only

​

Testing checklist

• Verify identical responses for wrong email vs wrong password
• Trigger validation errors and inspect errors structure
• Hit rate limits and ensure UI cooldown
• Test expired MFA challenges
• Switch X-App-Locale and verify translated messages