# too_many_requests

A throttle in a handler tripped; slow down and retry later (429).

## Meaning

A handler's own throttle refused the request:
- sign-in and registration attempts from one IP (`auth.brute_force.ip_max_attempts`
  per `ip_window`), failed sign-ins for one email address
  (`identifier_max_attempts`), or no password-hashing slot free within
  `verify_acquire_timeout`;
- a locked account while `auth.brute_force.reveal_lockout` is off, even with the
  right password;
- too many wrong second-factor codes (`mfa.max_failures`), or too many emailed codes;
- too many reset, verification or invitation emails for one user, including the
  admin API's resend operations.

## Impact

The user sees "Too many requests" with a wait. Occasional hits are expected from
guessing or from a user retrying quickly. Many legitimate users throttled at once
usually means the server sees every request as coming from one address, a proxy.

## Diagnosis

1. Look the request id up on the Troubleshooting page. Throttles are recorded as
   `auth.rate_limit.triggered` with `limit_scope` (`address`, `identifier`,
   `account_lock`, `verify_concurrency`, `mfa_shared`, `email_code`,
   `password_reset`, `invitation` and others).
2. `nauthera_auth_logins_total{result="throttled"}` shows the fleet-wide rate.
3. If one address dominates, check `security.client_ip.mode` and
   `security.trusted_proxies`; the dashboard's overview warns platform administrators
   when traffic seems to arrive through an unlisted proxy.

## Mitigation

- As a user: wait, then try again; repeated attempts do not shorten the wait.
- As a client developer: do not retry automatically.
- As an operator: list your proxies in `security.trusted_proxies`. A locked account
  is unlocked with `POST /v1/admin/orgs/{slug}/users/{id}/unlock` or by setting its
  password. `verify_concurrency` throttles mean too few hashing slots
  (`auth.brute_force.max_concurrent_verifies`) for the load.

## Escalation

Escalate when legitimate users are throttled with the proxies configured correctly,
or a throttle never clears. Open an issue with request ids, the `limit_scope`
values, the relevant `auth.brute_force.*` settings and the server version.

---

[Problem code runbooks](https://www.nauthera.io/docs/v1/runbooks/problems) · Generated from [`internal/runbook/problems.yaml`](https://github.com/nauthera/nauthera-server/blob/main/internal/runbook/problems.yaml) in nauthera-server.