Rate limits

There is no general per-second request quota. Two narrower mechanisms exist, and they behave differently enough that a client should handle them separately.

Credential throttles, 429#

Login, registration, password reset, email change, verification resend and refresh are each counted in a rolling window. The counters are database-backed, so they survive a restart and are shared across every server process, a client cannot escape one by reconnecting.

{ "detail": "Too many failed login attempts. Try again later." }

Failed logins are counted against the normalised email address, so alternating capitalisation does not reset the counter. Other throttles are counted per IP. A 429 is not retryable in a tight loop; wait out the window.

Generation admission, 503#

The document endpoints share a bounded pool of concurrent workers plus a queue. When both are full, further requests are rejected at the door rather than queued indefinitely. A request that will not be served for four minutes is worse than one that fails in four milliseconds.

Retry-After: 10

{
  "detail": {
    "code": "ai_busy",
    "message": "The AI service is handling too many requests right now. Please try again in a few seconds."
  }
}