# 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](https://www.rfc-editor.org/rfc/rfc7807), 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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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](https://dashboard.pdfblocks.com) et envoyez la requête en HTTPS. Voir
[Authentification](/docs/api/authentication).

### 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.

```json
{
  "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](/docs/api/regions-and-data-residency) valide.

### 406 : `Accept` inacceptable

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

```json
{
  "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](/docs/api/response-formats).

### Codes de statut réservés

<Note>
  **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](/docs/api/rate-limits-and-usage).
</Note>

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

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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](/docs/api/rate-limits-and-usage).

## 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](/docs/api/rate-limits-and-usage).

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