API Error Reference

Source of truth:

• d3chat/backend/app/routers/*.py
• d3chat/backend/app/dependencies.py
• d3chat/backend/app/middleware/rate_limit.py
• d3chat/backend/app/federation/inbox.py

Global Errors

401 Unauthorized

Returned when:

• access token invalid/expired/malformed
• user missing for token subject
• refresh token invalid on rotation
• federation signature headers invalid for protected federation routes

403 Forbidden

Returned when:

• role lacks required permission (admin, superadmin checks)
• non-member channel access
• registration mode disallows signup
• user banned/suspended on login

404 Not Found

Returned for missing entities (user/channel/message/device/setting/key bundle/avatar).

409 Conflict

Returned for uniqueness/conflict cases, for example:

• username already taken
• setting already exists
• user already in channel

429 Too Many Requests

Returned by:

• global middleware for IP request volume (RATE_LIMIT_PER_MINUTE)
• federation inbox per-origin rate limit

Auth Route Errors

POST /auth/register

• 403 Registration is currently closed
• 403 Registration is invite-only
• 403 Email domain '<domain>' is not allowed for registration
• 409 Username already taken

POST /auth/login

• 401 Invalid credentials
• 403 Account has been banned
• 403 Account suspended until <timestamp>

POST /auth/refresh

• 401 Invalid refresh token

User Route Errors

POST /users/me/avatar

• 400 File type not allowed
• 400 File too large

POST /users/me/password

• 400 Cannot change password for remote users
• 400 Current password is incorrect

GET /users/lookup

• 400 Invalid identity format, use user@server
• 404 User not found

Channel and Message Errors

Membership and role checks

• 403 Not a member of this channel
• 403 Requires role: owner

Message ownership checks

• 403 Can only edit own messages
• 403 Can only delete own messages

Member management

• 400 Cannot add members to a DM
• 409 User is already a member

Key Route Errors

• 404 Device not found
• 404 Key bundle not found
• 404 No X3DH setup data found

Admin Route Errors

Common moderation constraints:

• 400 Cannot ban/suspend/delete yourself
• 403 Only superadmins can ...
• 403 Cannot delete a superadmin

Federation Errors

Inbox

• 401 Missing federation headers
• 401 Invalid timestamp
• 401 Request outside replay window
• 401 Invalid signature
• 429 Federation rate limit exceeded

Client Implementation Guidance

1. Handle 401 by refreshing once, then forcing full logout if refresh fails.
2. Show actionable UI text for 403/409 cases.
3. Use endpoint-specific copy for auth failures to reduce support noise.
4. For 429, honor retry behavior (middleware uses Retry-After: 10).