# Codes d'erreur

Le champ `error.code` est **stable** : branchez votre logique dessus. Le `message` est destiné à l'affichage et peut changer sans préavis.

Le format et la politique de rejeu sont décrits dans [Erreurs et idempotence](/guides/erreurs).

## Authentification et clé

| Code | HTTP | Signification |
|---|---|---|
| `PAPI_KEY_MISSING` | 401 | en-tête `Authorization` absent ou mal formé |
| `PAPI_KEY_INVALID` | 401 | clé inconnue, secret erroné, ou préfixe d'une autre surface |
| `PAPI_KEY_REVOKED` | 401 | clé révoquée — elle ne reviendra pas, créez-en une nouvelle |
| `PAPI_KEY_EXPIRED` | 401 | clé arrivée à échéance |
| `PAPI_IP_FORBIDDEN` | 403 | adresse appelante hors de la liste autorisée sur cette clé |
| `PAPI_SCOPE_MISSING` | 403 | la clé ne porte pas le droit requis — le message le nomme |
| `PAPI_NOT_ENABLED` | 403 | l'accès API n'est pas ouvert sur votre compte |
| `RESELLER_INACTIVE` | 403 | compte apporteur inactif ou résilié |
| `FEATURE_DISABLED` | 404 | surface non ouverte — elle n'existe pas encore pour vous |
| `RATE_LIMIT_EXCEEDED` | 429 | limite de débit dépassée — voir les en-têtes `X-RateLimit-*` |

## Périmètre

Une ressource hors de votre portefeuille est **introuvable**, jamais « interdite » : l'API ne confirme pas l'existence de ce qui ne vous concerne pas.

| Code | HTTP | Signification |
|---|---|---|
| `COMPANY_NOT_FOUND` | 404 | entreprise inexistante, ou hors de votre portefeuille |
| `TRANSACTION_NOT_FOUND` | 404 | transaction inexistante, ou hors de votre portefeuille |
| `WALLET_NOT_FOUND` | 404 | aucun wallet pour cette entreprise |
| `USER_NOT_FOUND` | 404 | compte inexistant, ou hors du périmètre de l'entreprise ciblée |
| `CREDIT_REQUEST_NOT_FOUND` | 404 | demande inexistante, ou émise par un autre apporteur |
| `ENDPOINT_NOT_FOUND` | 404 | aucun endpoint à cette URL sur l'API partenaire |
| `RESELLER_NOT_FOUND` | 404 | compte apporteur introuvable — clé valide sur un compte qui n'existe plus |

## Portefeuille et comptes clients

| Code | HTTP | Signification |
|---|---|---|
| `COMPANY_ALREADY_EXISTS` | 409 | une entreprise porte déjà ce nom, ce RCCM ou ce NIF |
| `COMPANY_REQUEST_ALREADY_PENDING` | 409 | une demande d'enrôlement est déjà en cours pour cette immatriculation |
| `ACCOUNT_ALREADY_EXISTS` | 409 | un compte existe déjà avec l'email ou le téléphone fourni |
| `EMAIL_ALREADY_EXISTS` | 409 | un compte existe déjà avec cet email |
| `PHONE_ALREADY_EXISTS` | 409 | un compte existe déjà avec ce téléphone |
| `RESELLER_SELF_ASSIGNMENT` | 422 | coordonnées d'un compte apporteur — un compte client appartient au client |
| `RESELLER_COMPANY_QUOTA_EXCEEDED` | 422 | plafond d'entreprises au portefeuille atteint |
| `RESELLER_USER_QUOTA_EXCEEDED` | 422 | plafond de comptes web par entreprise atteint |
| `ROLE_NOT_ALLOWED` | 422 | rôle hors des deux valeurs acceptées (`FLEET_ADMINISTRATOR`, `DAF`) |
| `NO_UPDATABLE_FIELD` | 422 | aucun champ modifiable dans le corps |

## Wallet et crédit

| Code | HTTP | Signification |
|---|---|---|
| `RESELLER_CREDIT_DISABLED` | 403 | déclaration de versement non ouverte sur votre compte |
| `WALLET_BLOCKED` | 400 | wallet bloqué, aucun mouvement possible |
| `RESELLER_CREDIT_CAP_EXCEEDED` | 422 | plafond par opération dépassé |
| `RESELLER_DAILY_CAP_EXCEEDED` | 422 | plafond journalier dépassé, demandes en attente comprises |
| `PROOF_REQUIRED` | 400 | preuve de versement obligatoire sur toute déclaration |
| `PROOF_NO_FILE` | 400 | aucun fichier reçu sous le champ multipart `files` |
| `PROOF_TOO_MANY` | 400 | plus de 3 preuves |
| `PROOF_TOO_LARGE` | 413 | fichier au-delà de 10 Mo |
| `PROOF_INVALID_MIME` | 400 | type de fichier non accepté |
| `PROOF_MIME_MISMATCH` | 400 | le contenu du fichier ne correspond pas au type déclaré |
| `PROOF_INVALID` | 422 | preuve inexistante, supprimée, déjà liée, ou d'une autre entreprise |
| `PROOF_NOT_FOUND` | 404 | preuve introuvable ou supprimée |

## Requête

| Code | HTTP | Signification |
|---|---|---|
| `VALIDATION_ERROR` | 422 | validation échouée — `details` nomme les champs fautifs |
| `INVALID_PATH_PARAM` | 400 | identifiant de chemin non entier |
| `INVALID_QUERY_PARAM` | 400 | paramètre de query mal formé |
| `IDEMPOTENCY_KEY_MISSING` | 400 | en-tête `X-Idempotency-Key` absent sur une écriture |
| `IDEMPOTENCY_KEY_TOO_LONG` | 422 | clé d'idempotence au-delà de 200 caractères |
| `IDEMPOTENCY_CONFLICT` | 409 | même clé d'idempotence, corps différent |
| `INTERNAL_ERROR` | 500 | erreur serveur — réessayez avec backoff et la même clé d'idempotence |

<Callout type="tip" title="Codes inconnus">
  Cette liste couvre les codes rencontrés en intégration courante. Un code absent d'ici se traite génériquement selon son statut HTTP — jamais en silence.
</Callout>