Erreurs

Toutes les erreurs API retournent un corps de réponse JSON cohérent. Il existe deux formats d'erreur selon la source de l'erreur.

Erreurs de validation

Retourné lorsque la définition du document a des problèmes structuraux — JSON invalide, propriétés non reconnues ou incompatibilités de type. Ceux-ci sont détectés avant le début de la génération de PDF.

{
  "code": "SCHEMA_ERROR",
  "path": "$.document.content[0].tabel",
  "message": "Invalid value or unrecognized property at '$.document.content[0].tabel'."
}

Champ	Type	Description
code	string	Code d'erreur lisible par machine
path	string	Chemin JSON vers la propriété problématique
message	string	Description lisible par l'humain

Codes d'erreur de validation

Code	Description
INVALID_JSON	Le corps de la requête n'est pas un JSON valide
MISSING_ROOT	Propriété racine document manquante et aucun tableau content à encapsuler automatiquement
INVALID_DEFINITION	La définition du document est nulle après la désérialisation
EMPTY_CONTENT	Le tableau de contenu est présent mais vide
SCHEMA_ERROR	Nom de propriété non reconnu ou incompatibilité de type au chemin donné

Exemples

Faute de frappe dans le nom de la propriété :

// Request: { "document": { "content": [{ "tabel": {} }] } }

{
  "code": "SCHEMA_ERROR",
  "path": "$.document.content[0].tabel",
  "message": "Invalid value or unrecognized property at '$.document.content[0].tabel'."
}

Type incorrect :

// Request: { "document": { "pageSetup": { "margins": "50" }, "content": [{ "p": "Hi" }] } }

{
  "code": "SCHEMA_ERROR",
  "path": "$.document.pageSetup.margins",
  "message": "Invalid value or unrecognized property at '$.document.pageSetup.margins'."
}

Pas JSON :

{
  "code": "INVALID_JSON",
  "path": "$",
  "message": "Content does not appear to be JSON."
}

Contenu vide :

{
  "code": "EMPTY_CONTENT",
  "path": "document.content",
  "message": "Content array must contain at least one element."
}

Encapsulation automatique

Si vous envoyez une définition de document nue sans l'enveloppe document, l'API l'encapsulera automatiquement pour vous :

// This works:
{ "content": [{ "p": "Hello" }] }

// The API treats it as:
{ "document": { "content": [{ "p": "Hello" }] } }

Si ni document ni content n'est trouvé à la racine, l'API retourne une erreur MISSING_ROOT.

Erreurs serveur

Retourné par le gestionnaire d'exception global pour les erreurs d'infrastructure, d'autorisation et d'exécution. Utilise le format RFC 7807 Problem Details.

{
  "status": 503,
  "title": "Service Unavailable",
  "detail": "Database service is temporarily unavailable.",
  "instance": "/api/v1/{tenantId}/documents/generate-from-payload",
  "traceId": "00-abc123def456-789012-00",
  "errorCode": "DATABASE_UNAVAILABLE",
  "isRetryable": true,
  "retryAfterSeconds": 30
}

Champ	Type	Description
status	integer	Code de statut HTTP
title	string	Phrase de raison HTTP standard
detail	string	Description lisible par l'humain
instance	string	Chemin de la requête qui a déclenché l'erreur
traceId	string	ID de trace unique pour les demandes de support
errorCode	string	Code d'erreur lisible par machine
isRetryable	boolean	Si la requête peut être relancée
retryAfterSeconds	integer	Secondes à attendre avant de relancer (si relançable)

Codes de statut HTTP

État	Quand	Relançable
400	JSON invalide, erreurs de schéma, contenu vide, paramètres de requête incorrects	Non
401	Clé API manquante ou invalide	Non
403	Permissions insuffisantes ou incompatibilité de locataire	Non
404	Modèle ou document non trouvé	Non
429	Limite de débit dépassée	Oui — vérifiez l'en-tête X-RateLimit-Reset
500	Échec de la génération de PDF ou erreur serveur inattendue	Peut-être — relancer une fois
503	Base de données, stockage ou service externe temporairement indisponible	Oui — vérifiez retryAfterSeconds

Codes d'erreur serveur

Code	État	Description
VALIDATION_ERROR	400	Paramètres de requête invalides
INVALID_OPERATION	400	Opération non valide à l'état actuel
ACCESS_DENIED	401	Échec de l'authentification
TENANT_CLAIM_MISSING	403	Informations de locataire manquantes du jeton
TENANT_MISMATCH	403	Accès à une ressource d'un locataire différent
FILE_NOT_FOUND	404	Le fichier demandé n'existe pas
REQUEST_CANCELLED	400	Le client a annulé la requête
DATABASE_UNAVAILABLE	503	Base de données temporairement indisponible (relançable)
AZURE_SERVICE_ERROR	503	Service de stockage temporairement indisponible (relançable)
EXTERNAL_SERVICE_ERROR	503	Dépendance externe temporairement indisponible (relançable)
NETWORK_ERROR	503	Problème de connectivité réseau (relançable)
SERVICE_TIMEOUT	503	Délai d'attente de la requête dépassé
INTERNAL_ERROR	500	Erreur serveur inattendue

Limitation du débit

Les en-têtes de limite de débit sont inclus dans chaque réponse :

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1711843200

En-tête	Description
X-RateLimit-Limit	Requêtes maximales par minute pour votre plan
X-RateLimit-Remaining	Requêtes restantes dans la fenêtre actuelle
X-RateLimit-Reset	Horodatage Unix lorsque la limite de débit se réinitialise

Bonnes pratiques

1. Vérifiez le code de statut HTTP en premier avant d'analyser le corps de la réponse.
2. Utilisez code pour la gestion programmatique — correspondsur les codes d'erreur, pas sur les chaînes de message.
3. Utilisez path pour localiser le problème dans les erreurs de validation — il pointe vers la propriété JSON exacte.
4. Relancez sur 429 et 503 avec backoff. Utilisez retryAfterSeconds ou X-RateLimit-Reset pour déterminer le temps d'attente.
5. Ne relancez pas sur 400, 401, 403 ou 404 — corrigez d'abord la requête.
6. Enregistrez traceId pour les erreurs serveur — incluez-le lors de la prise de contact avec le support.
7. Validez localement avec le schéma JSON pour détecter les erreurs avant d'envoyer à l'API.