Erreurs#

Toutes les erreurs de l'API suivent un contrat unique : un objet JSON avec au moins une clé error.

{ "error": "Clé API invalide ou révoquée." }

Exception : les refus de validation Laravel (HTTP 422) répondent {"message": …, "errors": {…}}, sans clé error — voir la section Champs obligatoires du template.

Codes HTTP#

Code	Signification
400	Corps JSON déclaré mais non décodable (encodage non UTF-8, JSON invalide)
401	Clé manquante (Authorization: Bearer dfk_…) ou invalide/révoquée
403	Fonctionnalité non incluse dans le plan (voir not_in_plan ci-dessous)
404	Template ou dossier inconnu — ou hors de l'espace de la clé (on ne révèle pas l'existence d'une ressource étrangère)
409	Conflit : une requête avec la même Idempotency-Key est encore en cours (idempotency_in_progress) ou PDF indisponible sur GET /documents/{id}/pdf (pdf_draft, pdf_failed, pdf_missing)
422	Requête invalide (validation Laravel) ou paramètre métier refusé
429	Quota API du plan atteint (api_calls_per_month), cap de lots actifs ou pré-vol de quota documents
500	Le PDF n'a pas pu être généré (rare — rechargez ou contactez le support)
503	Pool de rendu synchrone saturé (pdf_busy) — relancez après Retry-After ou passez en async

Quotas : not_in_plan et quota_exceeded#

Les erreurs de quota portent un payload étendu :

{
  "error": "not_in_plan",
  "metric": "api_calls_per_month",
  "limit": null,
  "plan": "free",
  "message": "La fonctionnalité « Appels API » n'est pas incluse dans le plan FREE."
}

• not_in_plan (HTTP 403) : la fonctionnalité n'existe pas dans le plan — passez au plan supérieur.
• quota_exceeded (HTTP 429) : la limite mensuelle est atteinte — elle se réinitialise à la période suivante.

La clé message est localisée (fr/en) et peut être affichée telle quelle à l'utilisateur.

Champs obligatoires du template (422)#

Les variables et suivis marqués obligatoires dans le schéma du template sont exigés à la création d'un document — sur les POST unitaires comme sur les lots. Un champ manquant répond un 422 au format de validation Laravel, sans clé error :

{
  "message": "Le champ « Nom » est obligatoire.",
  "errors": {
    "nom": ["Le champ « Nom » est obligatoire."]
  }
}

• Les clés de errors sont les clés de variable du schéma (GET /templates/{public_id}/schema) ; pour un suivi obligatoire, la clé est préfixée tracking. (tracking.statut). Une variable de type référence requiert une fiche qui résout — message « La fiche « … » est obligatoire. ». Les messages sont libellés en français.
• La valeur compte dès qu'elle est résolue non vide : une cascade dossier/espace, un défaut du schéma, une formule ou la date dédiée du document satisfont l'exigence — fournir data n'est nécessaire que pour ce qui n'est pas pré-rempli.
• En cas d'erreurs multiples, errors les liste toutes et message reprend la première.
• La vérification précède le quota et toute écriture : un 422 ne réserve aucun numéro, ne crée aucun document et ne décompte rien.

Rendu synchrone saturé : pdf_busy (503)#

Les créations de documents sans async rendent le PDF pendant la requête, et chaque rendu synchrone occupe un créneau d'un pool limité. Quand le pool est saturé, l'appel est refusé avant toute création :

{
  "error": "pdf_busy",
  "message": "Le serveur est à pleine capacité de rendu synchrone. Réessayez dans quelques secondes ou utilisez async=true : la réponse part immédiatement et le PDF est rendu par la file (webhook document.pdf_ready si un endpoint est déclaré)."
}

La réponse porte l'en-tête Retry-After: 5. Relancez après 5 secondes, ou passez en async=true : le mode asynchrone n'occupe pas de créneau de rendu et répond 201 immédiatement (le PDF arrive ensuite par la file — webhook document.pdf_ready ou polling GET /documents/{id}).

Bonnes pratiques#

• Traitez 404 et 403 de la même façon côté intégration : ne distinguez pas « ressource absente » et « ressource d'un autre espace ».
• Sur 429, implémentez un backoff : réessayer immédiatement aggrave le compteur.
• Sur 400, journalisez le corps envoyé : c'est presque toujours un problème d'encodage côté client.

Génération en lot : erreurs spécifiques#

Les endpoints batch ajoutent deux payloads au contrat quota_exceeded (HTTP 429) :

{
  "error": "batch_limit_reached",
  "limit": 2,
  "message": "Vous avez déjà 2 lots en cours. Attendez leur achèvement ou récupérez-en un avant d'en créer un nouveau."
}

{
  "error": "quota_exceeded",
  "metric": "documents_per_month",
  "limit": 2000,
  "remaining": 1,
  "required": 3,
  "message": "Quota documents insuffisant : 1 restant(s) ce mois-ci pour 3 document(s) demandé(s)."
}

• batch_limit_reached : trop de lots actifs (pending/processing) dans l'espace — attendez la fin d'un lot (GET /batches/{id}) avant d'en créer un nouveau.
• quota_exceeded + remaining/required : le pré-vol de quota a refusé le lot entier plutôt que d'en émettre une partie — réduisez le lot ou attendez la période suivante.

Enfin, GET /documents/{public_id}/pdf renvoie 202 pdf_pending (rendu en cours, honore Retry-After), 409 (pdf_draft, pdf_failed, pdf_missing) et 410 (pdf_expired) — voir la référence.