[bitbiter-dev]

Closes #357

Summary

Auth failures change from an English sentence to Problem Details with a stable code. Status codes are unchanged.

 POST /api/v1/auth/login   → 401
-{ "error": "This account has been disabled. Please contact an administrator." }
+application/problem+json
+{ "status": 401, "code": "account_disabled", "detail": "This account has been disabled. …" }

 POST /api/v1/auth/register → 409
-{ "error": "Username is already taken." }
+{ "status": 409, "code": "username_taken", "detail": "…", "errors": { "username": ["username_taken"] } }

Endpoint	Codes
login, login/mobile	invalid_credentials 401, account_disabled 401, account_locked 429 + Retry-After
refresh	refresh_token_required 401, refresh_token_invalid 401, account_disabled 401, account_locked 429 + Retry-After
register	field: invalid_username/username_taken → username, invalid_email/email_taken → email, password_too_short/_too_long/_pwned → password; plain: invite_token_invalid 422
change-password	field: invalid_credentials 400 → currentPassword, password_* 422 → newPassword
rate limiter	rate_limited 429 + Retry-After

The rate limiter now sends Retry-After on every rejection. Both policies are sliding windows, which report no retry time, so this header was never sent before. Each policy now sends its whole window as Retry-After:

 SlidingWindowPolicy.OnRejected
-  if lease has RetryAfter (never, for a sliding window)
-    set Retry-After
+  set Retry-After = window   (60 s sensitive, 900 s refresh)
   write rate_limited problem

The following were decided with the maintainer while implementing:

• code is a Problem Details extension.
• type stays at its default. feat(api): Every error is a Problem Details response #364 should reuse code (see the comment there).
• The errors values are codes, not English text.

Admin endpoints are out of scope.

Evidence

The new tests (AuthErrorContractTests) post to the real endpoints on the in-process host. Each one asserts the status, the content type, code, detail, errors and Retry-After against literal values.

• Before: all 26 cases fail on the content type (application/json, not application/problem+json). The rate-limit cases fail on a missing Retry-After.
• After: the API unit suite passes, 671 of 671. scripts/mutation-changed.sh on the five changed source files reports 100.00%.

Merge Danger

Door: two-way

Nothing is deployed, and no client consumes these bodies yet. #360 is the first.

Blast Radius: auth-responses

Only the error bodies of the auth endpoints change, plus Retry-After on 429. Success responses and status codes are untouched.

🤖 Generated with Claude Code