Erreurs et limites

Les enveloppes d'erreur de chaque surface d'API, les codes d'erreur courants, les limites de débit, le verrouillage de compte et les plafonds de la plateforme.

Obexal a trois surfaces d'API, et chacune utilise la convention d'erreur attendue par son protocole. Cette page liste les formes, les codes stables et toutes les limites appliquées.

Formats d'erreur

API JSON (tout ce qui est sous /v1/) : une enveloppe unique sur chaque réponse non-2xx. code est une chaîne machine stable ; message est lisible par un humain et peut changer.

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

Endpoints OAuth (/oauth/*) : la forme RFC 6749, avec des champs snake_case au premier niveau.

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

Sur /oauth/authorize, les erreurs sont redirigées vers le client en paramètres de requête error, error_description et state une fois la redirect_uri validée ; avant cela, la réponse est un 400 direct (jamais de redirection ouverte). Un échec d'authentification client_secret_basic renvoie 401 avec un en-tête WWW-Authenticate: Basic. /oauth/userinfo renvoie 401 avec un en-tête WWW-Authenticate: Bearer error="invalid_token" (son corps utilise l'enveloppe JSON).

SCIM (/scim/v2/*) : le corps d'erreur SCIM standard, voir la référence SCIM.

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

Codes d'erreur courants de l'API

Des codes propres à chaque fonctionnalité existent aussi (par exemple slug_taken, email_taken, invalid_invite, password_expired) : traitez le statut HTTP comme la classe et le code comme la raison précise.

Codes d'erreur OAuth

Limites de débit

Les flux sensibles sont limités par fenêtres fixes, par e-mail et par IP cliente indépendamment. Deux familles existent ; leurs valeurs par défaut figurent dans la référence de configuration :

Les flux de vérification d'e-mail, de changement d'e-mail, d'invitation et de connexion sociale sont limités par les mêmes mécanismes. Dépasser une limite renvoie 429 rate_limited et l'évènement est consigné dans le journal d'audit.

Verrouillage de compte

Indépendamment des limites par IP, les échecs répétés de mot de passe verrouillent le compte lui-même, ce qui résiste à la rotation d'IP (LOGIN_LOCKOUT_MAX, LOGIN_LOCKOUT_WINDOW, LOGIN_LOCKOUT_DURATION) ; les valeurs par défaut figurent dans la référence de configuration. La réponse est 429 account_locked. Un administrateur peut lever le verrou avec POST /v1/admin/users/unlock.

Les codes à usage unique ont leurs propres plafonds : les OTP par e-mail autorisent 5 tentatives et expirent après 10 minutes ; les défis MFA autorisent 5 tentatives et expirent après 5 minutes (défauts).

Plafonds de la plateforme