PDF Blocks
TarifsSupport
Commencer gratuitement
Ouvrir la page

Erreurs

Le format d’erreur problem+json, la signification de chaque code de statut et comment traiter une requête en échec dans le code.

Quand une requête échoue, PDF Blocks renvoie un code de statut HTTP standard et un corps lisible par une machine décrivant ce qui s’est mal passé. Les erreurs suivent les problem details de la RFC 7807, si bien que vous analysez chaque échec de la même façon, quelle que soit l’action qui l’a produit.

Le modèle problem+json

Les réponses d’erreur ont Content-Type: application/problem+json et cette forme :

Attribut Type Description
type string Une URL vers la documentation du problème.
title string Un résumé du problème lisible par un humain.
status integer Le code de statut HTTP, repris dans le corps.
errors object Des noms de champs associés à des tableaux de messages.

L’URL type se termine toujours par le code de statut, par exemple https://www.pdfblocks.com/docs/api/v1/error/400, ce qui vous permet d’aiguiller dessus ou sur status. L’objet errors est présent quand un échec est lié à des champs précis de la requête (validation) ; pour les échecs au niveau de la requête, comme une clé d’API erronée, il peut être omis.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/400",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "file": [
      "Could not parse the PDF document. The file may be invalid or corrupt."
    ]
  }
}

Codes de statut

Statut Signification Que faire
400 Erreur de validation Corrigez les champs nommés et renvoyez.
401 Non autorisé Envoyez un X-API-Key valide.
404 Introuvable Vérifiez la route de l’action et l’hôte.
406 Accept inacceptable Demandez un format pris en charge.
402 Paiement requis (réservé) Réglez la facturation ou le quota.
403 Interdit (réservé) La clé n’a pas droit à cet appel.
413 Charge utile trop volumineuse (réservé) Envoyez un fichier plus petit.
429 Trop de requêtes (réservé) Ralentissez et réessayez.
5xx Erreur serveur (rare) Réessayez avec un délai croissant.

400 : erreur de validation

Un paramètre est invalide, ou file n’est pas un PDF lisible. L’objet errors nomme chaque champ fautif.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/400",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "line_1": ["The field line_1 must be a string with a maximum length of 32."]
  }
}

Lisez errors champ par champ, corrigez l’entrée et renvoyez la requête. Un 400 ne réussira pas à la nouvelle tentative sans modification.

401 : non autorisé

L’en-tête X-API-Key est absent, malformé, ou ne contient pas une clé valide.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/401",
  "title": "The request is missing a valid API key.",
  "status": 401
}

Renseignez l’en-tête X-API-Key avec une clé valide de votre dashboard et envoyez la requête en HTTPS. Voir Authentification.

404 : introuvable

Le chemin ne correspond à aucune action, en général à cause d’une faute de frappe dans le nom de l’action ou d’un segment de version manquant.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/404",
  "title": "The requested resource was not found.",
  "status": 404
}

Vérifiez la route (par exemple /v1/add_text_watermark) et le fait que vous appelez une URL de base valide.

406 : Accept inacceptable

Une action multi-documents a reçu un en-tête Accept qu’elle ne peut pas satisfaire.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/406",
  "title": "The requested Accept header cannot be satisfied.",
  "status": 406
}

Demandez l’un des formats pris en charge, application/zip, application/json ou multipart/mixed, ou omettez Accept pour obtenir le ZIP par défaut. Voir Formats de réponse et négociation de contenu.

Codes de statut réservés

Tourné vers l’avenir. Les réponses 402, 403, 413 et 429 font partie du contrat de l’API mais ne sont pas encore appliquées. Traitez-les dès maintenant pour que votre client soit prêt à leur mise en service. Les détails d’utilisation et de rate limiting se trouvent dans Rate limits et utilisation.

402 : paiement requis. Une condition de facturation ou de quota sur votre plan.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/402",
  "title": "Payment is required to complete this request.",
  "status": 402
}

403 : interdit. La clé est valide, mais n’a pas le droit d’utiliser cette ressource.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/403",
  "title": "You do not have permission to access this resource.",
  "status": 403
}

413 : charge utile trop volumineuse. Le corps de la requête dépasse la taille acceptée.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/413",
  "title": "The request payload is too large.",
  "status": 413
}

429 : trop de requêtes. Vous avez dépassé le débit autorisé par votre plan.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/429",
  "title": "Too many requests. Please retry later.",
  "status": 429
}

5xx : erreurs serveur

Un statut 5xx signale un problème de notre côté et reste rare. Il est transitoire : réessayez la même requête avec un délai exponentiel.

Traiter les erreurs dans le code

Analysez le corps une seule fois et aiguillez sur status (ou sur le statut final de type) :

  • 400 : lisez l’objet errors, rattachez chaque message à son champ et corrigez l’entrée. Ne réessayez pas à l’aveugle, car la même requête échouera de nouveau.
  • 401, 403, 404, 406 : la requête elle-même est erronée. Corrigez l’en-tête, la route ou Accept et renvoyez-la ; réessayer sans changement ne servira à rien.
  • 402, 413 : une condition de compte ou de taille. Réglez la facturation, ou envoyez un fichier plus petit ; en l’état, ces requêtes ne réussiront pas à la nouvelle tentative.
  • 429 et 5xx : transitoires. Réessayez avec un délai exponentiel, respectez l’en-tête Retry-After quand il est présent et limitez le nombre de tentatives. Voir Rate limits et utilisation.

Lisez toujours l’objet errors quand il est présent : il nomme exactement ce qu’il faut corriger.