Erreurs et codes de statut
Cette page est la référence consolidée des enveloppes de réponse utilisées par chaque route de l'API du domaine des prêts. La documentation de chaque route liste les codes de statut qu'elle émet ; cette page documente la forme de chaque enveloppe et le catalogue des valeurs code nommées que vous pouvez recevoir.
Lisez-la une fois avant l'intégration ; revenez-y chaque fois qu'un statut autre que 2xx vous surprend.
Catalogue des codes de statut
| Statut | Quand vous le rencontrez | Exemple de route |
|---|---|---|
200 OK | Lecture réussie, relecture idempotente, annulation logique, lot en masse traité, transition de statut. | Toutes les routes autres que de création. |
201 Created | Première création réussie sur une route unitaire. | POST /borrowers. |
202 Accepted | Import asynchrone démarré — le travail se poursuit en arrière-plan. | POST /imports. |
204 No Content | Actuellement renvoyé par aucune route du domaine des prêts. | — |
400 Bad Request | Échec de validation de la requête : JSON mal formé, paramètres de requête mal formés, violation de schéma. | Toutes les routes de modification. |
401 Unauthorized | Absence d'en-tête Authorization, jeton inconnu ou jeton révoqué. | Toutes les routes. |
403 Forbidden | L'appelant est un compte investisseur ; les investisseurs ne peuvent pas utiliser l'API de données de suivi (MONITORING_INVESTOR_FORBIDDEN). Un ?unmask=true par un non-administrateur ne renvoie pas 403 : il renvoie 200 avec les PII masquées. | Toutes les routes. |
404 Not Found | La ressource n'existe pas ou appartient à une autre organisation. | Toutes les routes qui référencent une ressource. |
409 Conflict | Une ligne active avec cet id existe déjà, une Idempotency-Key a été réutilisée pour une autre transition de statut, ou la phase de commit n'a pas pu voir le fichier téléversé. | POST /borrowers, PATCH /loans/.../status, POST /imports/{id}/commit. |
413 Payload Too Large | Un lot NDJSON en masse dépasse la limite de lignes ou d'octets. | POST /bulk/{entity}. |
422 Unprocessable Entity | Une ligne référencée n'existe pas à l'état actif dans le même portefeuille (REFERENCED_ENTITY_NOT_FOUND), ou la transition de statut demandée ne figure pas dans la matrice de transitions (INVALID_STATUS_TRANSITION). Les échecs de validation utilisent 400. | POST /loans, POST /payments, PATCH /loans/{loanRef}/status. |
429 Too Many Requests | Limite de débit dépassée. La plateforme applique des limites de débit par organisation ; l'en-tête de réponse Retry-After indique le nombre de secondes. | Toutes les routes. |
500 Internal Server Error | Erreur de plateforme non gérée. À traiter comme transitoire ; vous pouvez réessayer en toute sécurité avec la même Idempotency-Key. | Toutes les routes. |
Traitez tout 4xx autre que 429 comme un défaut de la requête — la logique de votre client doit rejeter l'entrée plutôt que de réessayer. Traitez 429 et 500 comme transitoires et réessayez avec un délai croissant ; une Idempotency-Key sécurise la nouvelle tentative.
Enveloppes standard
L'API du domaine des prêts utilise trois enveloppes de réponse pour les codes de statut d'échec. La forme de l'enveloppe vous indique le type d'échec auquel vous avez affaire.
Enveloppe de validation — 400 Bad Request
Utilisée pour les violations de schéma, les paramètres de requête mal formés et les chemins mal formés.
{
"error": "Validation failed",
"fieldErrors": [
{ "path": "interestRateApr", "message": "interestRateApr must be >= 0" },
{ "path": "termMonths", "message": "termMonths must be > 0" }
]
}| Champ | Type | Remarques |
|---|---|---|
error | chaîne | Bref résumé lisible. |
fieldErrors[].path | chaîne | Chemin pointé vers le champ en cause. (root) désigne le corps lui-même, par exemple lorsque l'analyse JSON a échoué. |
fieldErrors[].message | chaîne | Explication lisible. |
Certaines routes émettent errors[] plutôt que fieldErrors[] pour les échecs liés aux paramètres de requête (la convention du framework varie selon la surface). La forme path/message est identique ; traitez les deux noms de tableau comme interchangeables pour l'analyse.
Enveloppe à code nommé — 4xx
Utilisée lorsque l'échec a une cause précise que la plateforme désigne par une valeur code stable. La présence de fieldErrors est facultative et dépend de la possibilité d'attribuer l'échec à un champ précis.
{
"error": "a borrower with this id already exists",
"code": "ID_CONFLICT",
"fieldErrors": [
{ "path": "id", "message": "a borrower with this id already exists" }
]
}| Champ | Type | Remarques |
|---|---|---|
error | chaîne | Résumé lisible. |
code | chaîne | Code stable lisible par machine ; voir le glossaire. |
fieldErrors[] | tableau | absent | Présent lorsque l'échec concerne un champ précis. |
Certaines enveloppes portent un contexte structuré supplémentaire — par exemple, batch_too_large inclut un bloc fieldErrors indiquant la limite dépassée. La documentation de chaque route les précise.
Enveloppe d'erreur simple — 404 / 401
Utilisée pour les réponses laconiques, lorsqu'aucun contexte supplémentaire n'aiderait l'appelant. 404 en est l'exemple type :
{ "error": "Not found" }Certaines routes renvoient { "error": "...", "code": "NOT_FOUND" } ; considérez la présence ou l'absence de code sur un 404 comme informative, et non déterminante.
Deux espaces de codes : majuscules et minuscules
L'API du domaine des prêts utilise deux espaces de noms code distincts, volontairement séparés selon le mode d'ingestion :
- Les routes unitaires (les POST, les PATCH, l'annulation et les GET de rapprochement) émettent des valeurs de code en
UPPER_CASE:ID_CONFLICT,PORTFOLIO_NOT_FOUND,REFERENCED_ENTITY_NOT_FOUND,INVALID_STATUS_TRANSITION,CHECK_VIOLATION,NOT_FOUND,UNKNOWN_KIND,COMMIT_FAILED,IDEMPOTENCY_CONFLICT,IDEMPOTENCY_KEY_REUSED,MONITORING_INVESTOR_FORBIDDEN. Les routes NDJSON en masse renvoient elles aussiMONITORING_INVESTOR_FORBIDDENen majuscules. - Les routes NDJSON en masse émettent des valeurs de code en
lower_case:batch_too_large,portfolio_not_found,portfolio_id_required,invalid_body,invalid_json, ainsi que les codes par ligne documentés ci-dessous.
Lorsque votre client effectue un branchement sur code, respectez exactement la casse. Les deux espaces de codes sont stables chacun de leur côté ; ne les normalisez pas.
Glossaire des codes d'erreur
La plateforme associe un code stable à chaque mode d'échec nommé. Utilisez-les pour vos branchements programmatiques ; le texte du message error peut évoluer.
Espace de codes unitaire
| Code | Statut | Émis par | Déclencheur |
|---|---|---|---|
ID_CONFLICT | 409 | POST /borrowers, POST /loans, POST /payments. | Une ligne active avec le même id existe déjà. |
PORTFOLIO_NOT_FOUND | 404 | Toutes les routes d'écriture unitaire. | Le portfolioId du corps n'existe pas dans votre organisation. |
REFERENCED_ENTITY_NOT_FOUND | 422 | POST /loans, POST /payments. | borrowerId ou loanId référence une ligne qui n'existe pas à l'état actif dans le même portefeuille. |
INVALID_STATUS_TRANSITION | 422 | PATCH /loans/{loanRef}/status. | Le couple de statuts départ/arrivée ne figure pas dans la matrice de transitions. |
IDEMPOTENCY_CONFLICT | 409 | PATCH /loans/{loanRef}/status. | L'Idempotency-Key a déjà servi pour une autre transition de statut. Envoyez la nouvelle transition avec une nouvelle clé. |
IDEMPOTENCY_KEY_REUSED | 409 | POST /imports. | L'Idempotency-Key a déjà servi pour un import avec d'autres paramètres de requête (kind, filename, sizeBytes, …). La réponse inclut importId et mismatchedFields. Envoyez le nouvel import avec une nouvelle clé. |
MONITORING_INVESTOR_FORBIDDEN | 403 | Toutes les routes de suivi des prêts, NDJSON en masse comprises. | L'appelant est un compte investisseur ; les investisseurs ne peuvent pas utiliser l'API de données de suivi. |
CHECK_VIOLATION | 400 | POST /payments. | Une règle de données a échoué (généralement l'invariant d'abandon de créance ; la couche de schéma rejette la même forme dès la validation). |
NOT_FOUND | 404 | GET /borrowers/{id}, GET /payments/{id}, PATCH /loans/.../status, POST /payments/{id}/cancel, GET /loans/{externalId}. | La ligne recherchée n'existe pas à l'état actif dans le périmètre fourni, ou appartient à une autre organisation. |
UNKNOWN_KIND | 400 | POST /imports. | kind ne fait pas partie des six types de prêts. La réponse inclut un tableau allowed. |
COMMIT_FAILED | 409 | POST /imports/{id}/commit. | La plateforme n'a pas trouvé le fichier téléversé ; en général, le téléversement ne s'est jamais terminé. Relancez le téléversement, puis refaites le commit. |
Espace de codes NDJSON en masse
| Code | Statut | Déclencheur |
|---|---|---|
batch_too_large | 413 | Le corps dépasse 10 000 lignes ou 10 Mo. error et fieldErrors[].message distinguent la limite de lignes de la limite d'octets. |
portfolio_id_required | 400 | ?portfolioId=<UUID> est absent ou n'est pas un UUID valide. |
portfolio_not_found | 404 | Le ?portfolioId= n'existe pas à l'état actif dans votre organisation. |
invalid_body | 400 | Le corps de la requête n'a pas pu être lu comme du texte. |
invalid_json | (par ligne) | Une ligne n'est pas du JSON valide. Apparaît dans le tableau errors[] par ligne ; le lot renvoie 200. |
Un code absent de ce glossaire signifie que la plateforme a ajouté un nouveau code nommé depuis la dernière révision de cette page. Consignez toujours la valeur code telle quelle avec l'erreur de votre application, afin que l'équipe d'ingénierie puisse faire le rapprochement.
Codes d'erreur par ligne (en masse et imports asynchrones)
Le NDJSON en masse et les imports asynchrones renvoient tous deux des erreurs par ligne. La surface en masse utilise un ensemble de valeurs ; la surface des imports asynchrones utilise un ensemble similaire mais légèrement différent (elle inclut notamment validation_error au lieu de validation_failed, héritage d'une surface plus ancienne). Les entrées par ligne décrivent des échecs de lignes individuelles au sein d'un lot réussi, et non des échecs d'enveloppe.
Codes par ligne du NDJSON en masse
| Code par ligne | Déclencheur |
|---|---|
validation_failed | La ligne a échoué à la validation du schéma. Le champ message contient les erreurs de validation. |
fk_violation | Une référence de clé étrangère de la ligne (par ex. borrowerId, loanId) ne correspond à aucune ligne active du même portefeuille. |
unique_violation | Une ligne active avec le même (portfolio, externalId) ou le même id existe déjà. (Il n'existe pas de code par ligne id_conflict distinct ; les deux types de collision d'identifiant appelant apparaissent ici.) |
check_violation | Une règle de données a échoué — généralement la règle d'abandon de créance sur un paiement. |
db_error | Une erreur inattendue lors du stockage de cette ligne. La ligne est signalée en échec ; le lot se poursuit. |
invalid_json | La ligne n'était pas du JSON valide. La plateforme traite le reste du lot. |
Codes par ligne des imports asynchrones
| Code par ligne | Déclencheur |
|---|---|
parse_error | La ligne n'était pas du JSON valide. |
validation_error | La ligne a échoué à la validation du schéma. |
portfolio_mismatch | Le portfolioId de la ligne ne correspond pas au portefeuille d'ancrage de l'import. |
processor_error | Un échec inattendu du gestionnaire lors du traitement de cette ligne. |
Les erreurs survenant lors du stockage d'une ligne (référence manquante, doublon, règle de données non respectée) apparaissent sous l'un des codes ci-dessus, le détail figurant dans errorMessage.
Les erreurs par ligne ne remontent jamais en une réponse de premier niveau autre que 200 depuis la surface en masse — le lot dans son ensemble a réussi si la requête elle-même était bien formée ; les codes par ligne vous indiquent ce qui a été stocké.
Sémantique des nouvelles tentatives
Un schéma de nouvelle tentative sûr pour toute route de modification est le suivant :
- Générez une
Idempotency-Keydéterministe par opération logique. Un UUIDv4 accompagné d'un discriminant de route convient. - Envoyez la requête avec la clé.
- Pour tout
2xx,409 ID_CONFLICT,409 IDEMPOTENCY_CONFLICT,409 IDEMPOTENCY_KEY_REUSED,404,403,400,413ou422— ne réessayez pas. Le résultat est définitif. - Pour un
429— réessayez après le délai indiqué dans l'en-têteRetry-After. - Pour un
500ou une erreur réseau — réessayez un petit nombre fixe de fois avec un délai exponentiel. L'Idempotency-Keysécurise la nouvelle tentative, que la première ait abouti ou non.
Une nouvelle tentative d'une requête réussie avec la même Idempotency-Key renvoie la même réponse que l'originale, avec reused: true sur l'entité concernée. C'est la reprise canonique, dans le cas nominal, après une coupure réseau.
Ce que la plateforme ne renvoie jamais
Pour le débogage opérationnel, il est utile de connaître ce qui n'arrive jamais :
- Aucun code de statut
5xxn'est considéré comme une fonctionnalité par la plateforme. Un500est toujours un bogue à corriger ; n'écrivez jamais de logique client qui dépende d'une forme particulière de500. - Aucune réponse
404ne divulgue d'information sur les locataires. Un404sur une ligne qui existe dans une autre organisation est identique à un404sur une ligne qui n'existe nulle part. N'écrivez pas de logique client qui déduise l'existence d'une ressource chez un autre locataire. - Aucune réponse de succès ne porte de champ de corps nommé
success: false. Le code de statut fait foi pour déterminer si l'appel a réussi ; la forme du corps porte le détail. - Aucune route d'écriture ne renvoie son propre UUID sous forme de paramètre de chemin (en-tête « Location »). L'UUID créé apparaît dans le champ
iddu corps de la réponse.