Errors and limits

The error envelopes of each API surface, the common error codes, rate limits, account lockout and the platform caps.

Obexal has three API surfaces, and each uses the error convention its protocol expects. This page lists the shapes, the stable codes, and every enforced limit.

Error formats

JSON API (everything under /v1/): a single envelope on every non-2xx response. code is a stable machine string; message is human-readable and may change.

{"error": {"code": "rate_limited", "message": "too many requests"}}

OAuth endpoints (/oauth/*): the RFC 6749 shape, with snake_case fields at the top level.

{"error": "invalid_grant", "error_description": "code invalide, expiré ou déjà utilisé"}

On /oauth/authorize, errors are redirected to the client as error, error_description and state query parameters once the redirect_uri has been validated; before that, the response is a direct 400 (never an open redirect). A failed client_secret_basic authentication returns 401 with a WWW-Authenticate: Basic header. /oauth/userinfo returns 401 with a WWW-Authenticate: Bearer error="invalid_token" header (its body uses the JSON envelope).

SCIM (/scim/v2/*): the standard SCIM error body, see the SCIM reference.

{"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "status": "404", "detail": "utilisateur introuvable"}

Common API error codes

Feature-specific codes also exist (for example slug_taken, email_taken, invalid_invite, password_expired): treat the HTTP status as the class and the code as the precise reason.

OAuth error codes

Rate limits

Sensitive flows are throttled with fixed windows, keyed per e-mail and per client IP independently. Two families exist; their default values are in the configuration reference:

E-mail verification, e-mail change, invitation and social sign-in flows are throttled by the same limiters. Exceeding a limit returns 429 rate_limited and the event is recorded in the audit log.

Account lockout

Independently of IP-based limits, repeated password failures lock the account itself, which resists IP rotation (LOGIN_LOCKOUT_MAX, LOGIN_LOCKOUT_WINDOW, LOGIN_LOCKOUT_DURATION); the default values are in the configuration reference. The response is 429 account_locked. An administrator can lift the lock with POST /v1/admin/users/unlock.

One-time codes have their own caps: e-mail OTPs allow 5 attempts and expire after 10 minutes; MFA challenges allow 5 attempts and expire after 5 minutes (defaults).

Platform caps