Erreurs
Un seul format, des codes stables et documentés. Le message est destiné au développeur, jamais à l’utilisateur final.
HTTP/1.1 402 Payment Required
{ "error": { "code": "insufficient_credits",
"message": "Crédits insuffisants : 1 disponible(s), 2 requis",
"available_credits": 1, "required_credits": 2,
"purchase_url": "https://preprod-app.signatik.com/console/credits" } }| HTTP | code | Cause | Correctif |
|---|---|---|---|
| 400 | invalid_request | Corps ou paramètres invalides ; le message détaille le champ | Corriger le champ indiqué |
| 400 | invalid_document | PDF absent, vide, trop lourd (10 Mo) ou pas un PDF | Envoyer un PDF valide en base64 |
| 400 | invalid_field | document_index ou signer_index hors limites | Indexer depuis 0 dans les tableaux envoyés |
| 401 | unauthorized | Clé absente, mal formée ou révoquée | Vérifier l’en-tête Authorization |
| 402 | insufficient_credits | Solde insuffisant pour réserver le coût de l’enveloppe (libre-service). La réponse contient available_credits, required_credits et purchase_url | Acheter des crédits ou utiliser une clé sk_test_ |
| 403 | forbidden | Scope manquant sur la clé | Créer une clé avec le scope requis |
| 403 | advanced_not_enabled | Signature avancée non activée pour l’organisation | Nous contacter |
| 403 | authorization_required | Signature sans jeton d’autorisation (avancé) | Valider le code à usage unique d’abord |
| 404 | not_found | Ressource inconnue, ou appartenant à une autre organisation | — |
| 409 | invalid_status | Action impossible dans l’état courant (ex. envoyer une enveloppe déjà envoyée) | Lire GET /envelopes/:id avant d’agir |
| 409 | not_ready | Documents en préparation (avancé) : la notification part dès que c’est prêt | Réessayer après le webhook ou quelques secondes |
| 409 | identity_not_verified | Identité en attente de vérification | Créer d’abord l’identité via POST /identities |
| 409 | identity_expired | Identité échue | Ré-attester |
| 409 | mandate_not_active | Mandat non activé (acte non signé) ou révoqué | Faire signer l’acte de mandat |
| 409 | mandate_expired | Mandat hors période de validité | Créer un nouveau mandat |
| 409 | batch_mismatch | Le lot a changé depuis sa constitution (empreinte de la liste) | Recréer le lot |
| 409 | slot_closed | Créneau d’émargement clos : ne peut plus être rempli | — |
| 409 | document_changed | Le document affiché ne correspond plus au jeton d’autorisation | Recharger la page de signature |
| 410 | gone | Lien de signature expiré ou annulé, feuille purgée | — |
| 413 | payload_too_large | Corps > 64 Mo | Réduire le nombre ou le poids des PDF |
| 422 | identity_required | signature_level "advanced" sans identity ni identity_id — jamais contournable | Transmettre l’identité attestée |
| 422 | phone_required | Authentification par SMS sans numéro | Renseigner phone (E.164) |
| 422 | mandate_required | organization_seal sans mandate_id | Créer le mandat |
| 422 | agent_not_in_mandate | Le signataire n’est pas mandataire du mandat | Utiliser un mandataire déclaré |
| 429 | rate_limited | Trop de requêtes ; en-tête Retry-After | Attendre le délai indiqué |
| 429 | too_many_attempts | Cinq codes faux : demander un nouveau code | — |
| 503 | idv_not_configured | Vérification d’identité à distance non contractualisée | Nous contacter |
| 503 | payments_not_configured | Paiement en ligne indisponible | Nous contacter |
Les erreurs 5xx non listées renvoient internal_error ; réessayez avec attente exponentielle. Une création d’enveloppe qui a renvoyé 5xx peut avoir laissé un brouillon : listez avant de recréer.