Waafir
Cette page est une traduction automatique en attente de relecture humaine. Elle peut contenir des erreurs.

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

StatutQuand vous le rencontrezExemple de route
200 OKLecture réussie, relecture idempotente, annulation logique, lot en masse traité, transition de statut.Toutes les routes autres que de création.
201 CreatedPremière création réussie sur une route unitaire.POST /borrowers.
202 AcceptedImport asynchrone démarré — le travail se poursuit en arrière-plan.POST /imports.
204 No ContentActuellement 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 UnauthorizedAbsence d'en-tête Authorization, jeton inconnu ou jeton révoqué.Toutes les routes.
403 ForbiddenL'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 FoundLa ressource n'existe pas ou appartient à une autre organisation.Toutes les routes qui référencent une ressource.
409 ConflictUne 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 LargeUn lot NDJSON en masse dépasse la limite de lignes ou d'octets.POST /bulk/{entity}.
422 Unprocessable EntityUne 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 RequestsLimite 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 ErrorErreur 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" }
  ]
}
ChampTypeRemarques
errorchaîneBref résumé lisible.
fieldErrors[].pathchaîneChemin pointé vers le champ en cause. (root) désigne le corps lui-même, par exemple lorsque l'analyse JSON a échoué.
fieldErrors[].messagechaîneExplication 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" }
  ]
}
ChampTypeRemarques
errorchaîneRésumé lisible.
codechaîneCode stable lisible par machine ; voir le glossaire.
fieldErrors[]tableau | absentPré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 aussi MONITORING_INVESTOR_FORBIDDEN en 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

CodeStatutÉmis parDéclencheur
ID_CONFLICT409POST /borrowers, POST /loans, POST /payments.Une ligne active avec le même id existe déjà.
PORTFOLIO_NOT_FOUND404Toutes les routes d'écriture unitaire.Le portfolioId du corps n'existe pas dans votre organisation.
REFERENCED_ENTITY_NOT_FOUND422POST /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_TRANSITION422PATCH /loans/{loanRef}/status.Le couple de statuts départ/arrivée ne figure pas dans la matrice de transitions.
IDEMPOTENCY_CONFLICT409PATCH /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_REUSED409POST /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_FORBIDDEN403Toutes 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_VIOLATION400POST /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_FOUND404GET /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_KIND400POST /imports.kind ne fait pas partie des six types de prêts. La réponse inclut un tableau allowed.
COMMIT_FAILED409POST /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

CodeStatutDéclencheur
batch_too_large413Le 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_required400?portfolioId=<UUID> est absent ou n'est pas un UUID valide.
portfolio_not_found404Le ?portfolioId= n'existe pas à l'état actif dans votre organisation.
invalid_body400Le 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 ligneDéclencheur
validation_failedLa ligne a échoué à la validation du schéma. Le champ message contient les erreurs de validation.
fk_violationUne référence de clé étrangère de la ligne (par ex. borrowerId, loanId) ne correspond à aucune ligne active du même portefeuille.
unique_violationUne 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_violationUne règle de données a échoué — généralement la règle d'abandon de créance sur un paiement.
db_errorUne erreur inattendue lors du stockage de cette ligne. La ligne est signalée en échec ; le lot se poursuit.
invalid_jsonLa ligne n'était pas du JSON valide. La plateforme traite le reste du lot.

Codes par ligne des imports asynchrones

Code par ligneDéclencheur
parse_errorLa ligne n'était pas du JSON valide.
validation_errorLa ligne a échoué à la validation du schéma.
portfolio_mismatchLe portfolioId de la ligne ne correspond pas au portefeuille d'ancrage de l'import.
processor_errorUn é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 :

  1. Générez une Idempotency-Key déterministe par opération logique. Un UUIDv4 accompagné d'un discriminant de route convient.
  2. Envoyez la requête avec la clé.
  3. Pour tout 2xx, 409 ID_CONFLICT, 409 IDEMPOTENCY_CONFLICT, 409 IDEMPOTENCY_KEY_REUSED, 404, 403, 400, 413 ou 422 — ne réessayez pas. Le résultat est définitif.
  4. Pour un 429 — réessayez après le délai indiqué dans l'en-tête Retry-After.
  5. Pour un 500 ou une erreur réseau — réessayez un petit nombre fixe de fois avec un délai exponentiel. L'Idempotency-Key sé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 5xx n'est considéré comme une fonctionnalité par la plateforme. Un 500 est toujours un bogue à corriger ; n'écrivez jamais de logique client qui dépende d'une forme particulière de 500.
  • Aucune réponse 404 ne divulgue d'information sur les locataires. Un 404 sur une ligne qui existe dans une autre organisation est identique à un 404 sur 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 id du corps de la réponse.