Erreurs

Formes d’erreur

Il y a trois formes. Lisez d’abord le statut, puis le corps. 1. detail est une chaîne (la plupart des erreurs).

{ "detail": "Invalid or revoked API key" }

2. detail est un objet avec un code stable (faites correspondre sur code, pas sur le message).

{
  "detail": {
    "code": "kyc_extract_cap_reached",
    "message": "Monthly document-read limit of 2000 reached.",
    "used": 2000,
    "limit": 2000
  }
}

3. code et message au niveau supérieur, sans detail. Ces erreurs viennent du limiteur de débit, du gestionnaire de route inconnue et du filet de sécurité pour les erreurs inattendues.

{ "code": "rate_limit_exceeded", "message": "Too many requests. Please slow down." }

Une erreur de schéma 422 a une liste dans detail, une entrée par champ invalide :

{
  "detail": [
    { "type": "string_pattern_mismatch", "loc": ["body", "reference"], "msg": "String should match pattern '^[A-Za-z0-9_.:-]+$'", "input": "client 1", "ctx": { "pattern": "^[A-Za-z0-9_.:-]+$" } }
  ]
}

loc indique où : ["body", "reference"] pour un corps JSON, ["query", "environment"] ou ["path", "key"]. Pour un champ de formulaire multipart, le premier élément est aussi body. Gérez les trois formes : un client qui suppose que detail est toujours un objet échouera à la première 422.

Identifiant de requête

Chaque réponse porte X-Request-ID. Si vous envoyez le vôtre (1 à 64 caractères parmi A-Z a-z 0-9 . _ : -), Sahl le renvoie ; sinon Sahl en crée un. Chaque appel de clé est listé dans Developers, Call log dans la console sous cet identifiant. Citez-le quand vous écrivez à Sahl.

Catalogue

400 Requête invalide

Message	Cause	Correctif
`Send between 1 and 5 files.`	`/extract` n’a reçu aucun fichier ou plus de 5.	Envoyez 1 à 5 parties `files`.
`Unsupported file type '<mime>'. Allowed types: application/pdf, image/jpeg, image/png, image/tiff, image/webp`	Le `Content-Type` de la partie n’est pas l’un des cinq. `image/jpg` est accepté comme JPEG.	Convertissez le fichier ou définissez le bon type de contenu sur la partie.
`File content does not match declared MIME type.`	Les premiers octets ne correspondent pas au type de contenu déclaré (un PNG envoyé comme `application/pdf`, ou un fichier qui n’est ni une image ni un PDF).	Envoyez le vrai fichier avec son vrai type. Un PDF peut avoir jusqu’à 1 Ko avant `%PDF-`.

401 Non autorisé

Message	Cause	Correctif
`Missing API key`	Pas d’en-tête `Authorization: Bearer ...`.	Envoyez-le.
`Invalid or revoked API key`	Clé incorrecte, mal formée ou révoquée.	Vérifiez la clé. Créez-en une nouvelle si elle a été révoquée.
`API key expired`	Une clé renouvelée dont la période de grâce est terminée.	Utilisez la nouvelle clé.
`Partner identity could not be verified`	La clé est liée à un compte de service et `X-Partner-Identity` est absent ou incorrect.	Envoyez un jeton d’identité Google valide pour le compte lié et l’audience indiquée dans le formulaire de la clé.

403 Interdit

Corps	Cause	Correctif
`"API key lacks the kyc:verify scope"` (chaîne, le nom du scope varie)	La clé ne détient pas le scope de l’endpoint.	Créez une clé avec ce scope. Voir scopes.
`{"code": "kyc_scope_not_allowed", "message": "This workspace is not enabled for the partner KYC API."}`	La clé a un scope `kyc:` mais l’espace de travail n’est pas activé (l’accès à l’API partenaire est par espace de travail).	Demandez un accès bac à sable.
`{"code": "direct_access_refused", "message": "Call the API at https://app.sahlfinancial.com/api."}`	Vous avez appelé l’adresse interne de Sahl.	Utilisez l’hôte public.

404 Introuvable

Corps	Cause	Correctif
`{"detail": "identity verification is not set up for this tenant"}`	Un endpoint eID sur un espace de travail sans compte chez un fournisseur eID.	Contactez Sahl pour activer l’eID.
`{"detail": "Not Found"}`	`GET /v1/kyc/eid/{key}` ou son rapport : la clé n’existe pas, ou appartient à un autre espace de travail.	Utilisez le `key` que votre `POST /v1/kyc/eid` a renvoyé.
`{"code": "not_found", "message": "API endpoint not found: GET /api/..."}`	Le chemin ou la méthode n’existe pas.	Vérifiez le chemin. L’URL de base se termine par `/api`.

413 Charge trop volumineuse

Message	Cause	Correctif
`File too large. Maximum allowed size is 30 MB.`	Un fichier dépasse la limite (30 Mo par défaut).	Compressez ou découpez.
`Image is 9000x9000 pixels; the maximum is 50 megapixels.`	L’en-tête de l’image déclare plus de 50 mégapixels. Un petit fichier peut quand même être refusé.	Réduisez la taille.
`Image dimensions are too large to process.`	Pillow a signalé une bombe de décompression.	Envoyez une image normale.

422 Non traitable

Message	Cause	Correctif
`reference must be 1-64 characters of A-Z a-z 0-9 _ . : -`	Champ de formulaire de `/extract`.	Utilisez seulement ces caractères.
`environment must be 'sandbox' or 'production'`	Champ de formulaire de `/extract`.	Utilisez l’une des deux valeurs.
`subject must be at most 255 characters`	Champ de formulaire de `/extract`.	Raccourcissez-le.
`identity verification is available for Canadian clients only`	`/v1/kyc/eid` avec un `country` qui n’est ni `CA` ni `CAN`.	L’eID est réservé aux clients canadiens.
Une liste de `{type, loc, msg}`	Un champ JSON, de requête ou de chemin échoue au schéma : un `reference` ou `environment` invalide, `email` qui n’est pas un courriel, `documents` qui n’en contient ni 1 ni 2, `key` qui n’est pas un entier, un champ obligatoire manquant.	Lisez `loc` et `msg`.

Un kind invalide n’est pas une erreur : les valeurs inconnues comptent comme individual.

429 Trop de requêtes

Corps	Cause	Correctif
`{"detail": {"code": "kyc_extract_cap_reached", "message": "Monthly document-read limit of 2000 reached.", "used": 2000, "limit": 2000}}`	L’espace de travail a utilisé ses lectures du mois calendaire (UTC). Compté avant l’exécution du modèle, donc un appel refusé ne consomme rien.	Attendez le mois suivant, ou demandez à Sahl de relever la limite. Ne réessayez pas.
`{"code": "rate_limit_exceeded", "message": "Too many requests. Please slow down."}`	Plus de 100 requêtes par minute depuis une même IP cliente sur ces routes. En-têtes : `Retry-After` (secondes), `X-RateLimit-Limit`, `X-RateLimit-Remaining`.	Attendez `Retry-After` secondes.

Chaque réponse réussie porte aussi X-RateLimit-Limit et X-RateLimit-Remaining. La limite est par IP cliente, pas par clé, donc plusieurs serveurs derrière une même adresse la partagent. 100 par minute est la valeur par défaut dans le code et peut changer.

500 et 502

Statut	Corps	Cause	Correctif
500	`{"code": "internal_error", "message": "An unexpected error occurred", "details": null}`	Une défaillance inattendue du côté de Sahl.	Réessayez une fois. Si elle persiste, citez `X-Request-ID`.
502	`{"detail": "the identity verification service did not answer"}`	Le fournisseur eID n’a pas répondu.	Réessayez plus tard.

Un lecteur injoignable n’est pas une erreur : /extract répond 200 avec reader_unavailable: true. Voir Lire des documents.

Nouvelles tentatives

L’API n’a pas de clé d’idempotence. Réfléchissez à chaque appel avant de le réessayer.

Appel	Réessai sans risque ?	Ce que fait un réessai
`GET /v1/kyc/eid/{key}` et `/report`	Oui	Lit de nouveau.
`POST /v1/kyc/verify`, `POST /v1/kyc/assess`	Oui en pratique	Le verdict est une fonction pure du corps. Un réessai avec une `reference` classe de nouveau le verdict sur le dossier et renvoie le webhook. Dédupliquez sur `event_id`.
`POST /v1/kyc/extract`	Seulement après une défaillance réseau ou une 5xx	Lit de nouveau et compte de nouveau. Avec une `reference`, il classe de nouveau les documents, donc le dossier en contient alors deux copies.
`POST /v1/kyc/eid`	À éviter	Envoie de nouveau un courriel au client et remplace la demande enregistrée sur le dossier.

Règles pratiques :

Ne réessayez jamais une 4xx, sauf une 429 pour rate_limit_exceeded, qui a Retry-After. Une 4xx échouera de la même façon.
Réessayez une 5xx et un délai d’attente réseau avec un backoff exponentiel et un plafond, par exemple 2 s, 4 s, 8 s, puis arrêtez.
Fixez un délai d’attente client bien supérieur au temps de réponse habituel. Les exemples utilisent 120 secondes pour /extract.
Après un délai d’attente sur /extract, vous ne savez pas si la lecture a eu lieu. Consultez Documents pour la reference avant de renvoyer, ou acceptez le doublon.

Démarrer

Connexions bancaires et open banking

Documents (OCR)

Vérification et eID

Évaluation du risque et scoring

Construire

Référence

Console uniquement

Formes d’erreur

Identifiant de requête

Catalogue

400 Requête invalide

401 Non autorisé

403 Interdit

404 Introuvable

413 Charge trop volumineuse

422 Non traitable

429 Trop de requêtes

500 et 502

Nouvelles tentatives

​Formes d’erreur

​Identifiant de requête

​Catalogue

​400 Requête invalide

​401 Non autorisé

​403 Interdit

​404 Introuvable

​413 Charge trop volumineuse

​422 Non traitable

​429 Trop de requêtes

​500 et 502

​Nouvelles tentatives

Formes d’erreur

Identifiant de requête

Catalogue

400 Requête invalide

401 Non autorisé

403 Interdit

404 Introuvable

413 Charge trop volumineuse

422 Non traitable

429 Trop de requêtes

500 et 502

Nouvelles tentatives