Skip to main content

Error Handling & UX Patterns

A great authentication system is invisible until something goes wrong. Handling authentication errors gracefully is key to a high-quality Archibald application.

Common Error Scenarios​

1. Invalid Credentials​

When a login fails due to wrong username or password.

  • UX Practice: Show a generic "Invalid username or password" message. Do not specify which one is wrong, as this helps prevent user enumeration attacks.
  • Code: Use the error state returned by the useLogin hook.

2. Session Expiration​

When the user's nct and ncr tokens are both invalid or expired.

  • UX Practice: Instead of an abrupt "401 Unauthorized" error page, redirect the user to the login page with a returnPath query parameter. After login, redirect them back to where they were.
  • Code: Use the RestrictedRoute component which handles this pattern automatically.

3. Account Lockout​

After multiple failed login attempts.

  • UX Practice: Notify the user that their account is temporarily locked and provide clear instructions on how to unlock it (e.g., via email or a wait timer).

Global Error Listeners​

You can use the SessionClient.subscribe method to listen for authentication errors globally and trigger UI feedback (like a "Your session has expired" toast).

// src/client/init.ts
sessionClient.subscribe(['error'], (event) => {
    Notifications.show('Your session has expired. Please log in again.');
});

"Silent" Refresh Failures​

If the background refresh flow fails (e.g., due to network issues), the user might still be logged in locally but unable to make API calls.

  • Best Practice: Monitor the refetch state of your data hooks. If a 401 is returned despite the SessionClient saying isLoggedIn === true, trigger a manual sessionClient.check().