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

Renvoyées avec HTTP 400 lorsque la définition du document est refusée avant tout rendu ou toute facturation : un texte qui n'est pas du JSON, une clé ou une valeur que le schéma ne nomme pas, un membre obligatoire manquant, ou une limite dépassée. La définition est lue exactement comme le schéma publié l'énonce : une clé dans une autre casse, une orthographe retirée ou une définition sans sa racine est refusée, jamais devinée.

{
  "code": "SCHEMA",
  "path": "document.content.0",
  "message": "\"tabel\" is not in this schema; this object takes: source, break, p, th, td, h1, h2, h3, h4, h5, h6, title, lang, id, ol, ul, table, image, hr, columns, svg, toc, style, header, and 8 more"
}

Champ	Type	Description
code	string	Code d'erreur lisible par machine
path	string	L'endroit dans la définition, en clés et indices séparés par des points (document.content.0)
message	string	Ce qui ne va pas, et ce que cet endroit accepte à la place

Codes d'erreur de validation

Code	Description
INVALID_JSON	Le corps de la requête n'est pas du JSON
SCHEMA	Une clé que le schéma ne nomme pas, une valeur du mauvais type, un membre obligatoire manquant, ou une définition sans racine document ni component
EMPTY_CONTENT	Un document dont le tableau content est vide
UNRESOLVED_COMPONENT	Un use nomme un composant que le locataire n'a pas

Une définition qui dépasse une des limites de ressources du moteur (trop de pages, un tableau ou une image trop grands, une imbrication trop profonde) est refusée avec un code qui nomme la limite, comme TOO_MANY_PAGES ou NESTING_TOO_DEEP.

Exemples

Faute de frappe dans un nom de propriété, pour { "document": { "content": [{ "tabel": {} }] } } : la réponse ci-dessus.

Mauvais type, pour { "document": { "pageSetup": { "margin": true }, "content": [{ "p": "Hi" }] } } :

{
  "code": "SCHEMA",
  "path": "document.pageSetup.margin",
  "message": "Expected a number, CSS's spacing shorthand (\"20mm\", \"10mm 20mm\") or a list of four lengths - numbers in points or unit strings (\"0.5in\", \"12.7mm\", \"48px\", \"36pt\")."
}

Contenu vide, pour { "document": { "content": [] } } :

{
  "code": "EMPTY_CONTENT",
  "path": "document.content",
  "message": "the content array is empty, so the document draws nothing; give it at least one node (a component may be config-only, a document may not)"
}

La clé racine est obligatoire

Une définition s'écrit dans document, un composant dans component. Un { "content": [...] } nu est refusé avec SCHEMA, et le message dit où le placer :

{
  "code": "SCHEMA",
  "path": "$",
  "message": "\"content\" is not in this schema; this object takes: $schema, document, component; a definition is written inside \"document\" ({\"document\": ...}), a component inside \"component\""
}

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": "/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	Jeton d'accès manquant, invalide ou expiré, ou identifiants client incorrects	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 — attendez les secondes indiquées par l'en-tête Retry-After
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

Une requête au-delà d'une limite de débit reçoit 429 Too Many Requests. L'en-tête Retry-After donne le nombre de secondes à attendre avant la réinitialisation de la limite :

HTTP/1.1 429 Too Many Requests
Retry-After: 37

{"error": "rate_limit_exceeded", "message": "Too many requests. Please try again later."}

Les limites elles-mêmes sont indiquées dans Limites de débit.

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 l'en-tête Retry-After 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.