# Errori

Il formato di errore problem+json, che cosa significa ogni codice di stato e come gestire nel codice una richiesta non riuscita.

Quando una richiesta non riesce, PDF Blocks restituisce un codice di stato HTTP
standard e un corpo leggibile da una macchina che descrive che cosa è andato
storto. Gli errori seguono i problem details della
[RFC 7807](https://www.rfc-editor.org/rfc/rfc7807), quindi ogni errore si
analizza allo stesso modo, indipendentemente dall’azione che lo ha prodotto.

## Il modello problem+json

Le risposte di errore hanno `Content-Type: application/problem+json` e questa
forma:

| Attributo | Tipo    | Descrizione                                              |
| --------- | ------- | -------------------------------------------------------- |
| `type`    | string  | Un URL alla documentazione relativa al problema.         |
| `title`   | string  | Un riepilogo del problema leggibile da una persona.      |
| `status`  | integer | Il codice di stato HTTP, riportato anche nel corpo.      |
| `errors`  | object  | Nomi di campo associati ad array di messaggi di errore.  |

L’URL `type` termina sempre con il codice di stato (ad esempio
`https://www.pdfblocks.com/docs/api/v1/error/400`), quindi è possibile ramificare
il codice su di esso oppure su `status`. L’oggetto `errors` è presente quando un
errore è legato a campi specifici della richiesta (validazione); per gli errori a
livello di richiesta, come una chiave API errata, può essere omesso.

```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."
    ]
  }
}
```

## Codici di stato

| Stato  | Significato                         | Che cosa fare                                     |
| ------ | ----------------------------------- | ------------------------------------------------- |
| `400`  | Errore di validazione               | Correggere i campi indicati e reinviare.          |
| `401`  | Non autorizzato                     | Inviare un `X-API-Key` valido.                    |
| `404`  | Non trovato                         | Verificare il percorso dell’azione e l’host.      |
| `406`  | `Accept` non accettabile            | Richiedere un formato supportato.                 |
| `402`  | Pagamento richiesto *(riservato)*   | Risolvere la fatturazione o la quota.             |
| `403`  | Vietato *(riservato)*               | La chiave non è autorizzata per questa chiamata.  |
| `413`  | Payload troppo grande *(riservato)* | Inviare un file più piccolo.                      |
| `429`  | Troppe richieste *(riservato)*      | Rallentare e riprovare.                           |
| `5xx`  | Errore del server (raro)            | Riprovare con backoff.                            |

### 400: errore di validazione

Un parametro non è valido oppure `file` non è un PDF leggibile. L’oggetto
`errors` indica ogni campo in errore.

```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."]
  }
}
```

Leggere `errors` campo per campo, correggere l’input e reinviare la richiesta. Un
`400` non andrà a buon fine al nuovo tentativo senza modifiche.

### 401: non autorizzato

L’intestazione `X-API-Key` è assente, malformata oppure non contiene una chiave
valida.

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

Impostare l’intestazione `X-API-Key` con una chiave valida presa dalla
[dashboard](https://dashboard.pdfblocks.com) e inviare la richiesta su HTTPS.
Vedere [Autenticazione](/docs/api/authentication).

### 404: non trovato

Il percorso non corrisponde a nessuna azione, di solito per un errore di
battitura nel nome dell’azione o per un segmento di versione mancante.

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

Verificare il percorso (ad esempio `/v1/add_text_watermark`) e che si stia
chiamando un [URL di base](/docs/api/regions-and-data-residency) valido.

### 406: `Accept` non accettabile

Un’azione a più documenti ha ricevuto un’intestazione `Accept` che non può
soddisfare.

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

Richiedere uno dei formati supportati (`application/zip`, `application/json` o
`multipart/mixed`) oppure omettere `Accept` per ottenere lo ZIP predefinito.
Vedere [Formati di risposta](/docs/api/response-formats).

### Codici di stato riservati

<Note>
  **Uno sguardo al futuro.** Le risposte `402`, `403`, `413` e `429` fanno parte
  del contratto dell’API ma **non sono ancora applicate**. Conviene gestirle fin
  d’ora, così il client sarà pronto quando entreranno in vigore. I dettagli su
  utilizzo e rate limiting si trovano in
  [Rate limit e utilizzo](/docs/api/rate-limits-and-usage).
</Note>

**`402`: pagamento richiesto.** Una condizione di fatturazione o di quota sul
piano in uso.

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

**`403`: vietato.** La chiave è valida ma non è autorizzata a usare questa
risorsa.

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

**`413`: payload troppo grande.** Il corpo della richiesta supera la dimensione
accettata.

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

**`429`: troppe richieste.** È stato superato il rate limit previsto dal piano.

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

### 5xx: errori del server

Uno stato `5xx` segnala un problema dalla nostra parte ed è raro. È transitorio:
riprovare la stessa richiesta con un
[backoff esponenziale](/docs/api/rate-limits-and-usage).

## Gestire gli errori nel codice

Analizzare il corpo una sola volta e ramificare il codice in base a `status`
(oppure allo stato finale in `type`):

- **`400`**: leggere l’oggetto `errors`, ricondurre ogni messaggio al proprio
  campo e correggere l’input. Non riprovare alla cieca: la stessa richiesta
  fallirà di nuovo.
- **`401`, `403`, `404`, `406`**: la richiesta stessa è errata. Correggere
  l’intestazione, il percorso o `Accept` e reinviarla; riprovare senza modifiche
  non serve.
- **`402`, `413`**: una condizione di account o di dimensione. Risolvere la
  fatturazione oppure inviare un file più piccolo; così come sono, queste
  richieste non andranno a buon fine al nuovo tentativo.
- **`429` e `5xx`**: transitori. Riprovare con backoff esponenziale, rispettare
  l’intestazione `Retry-After` quando è presente e limitare il numero di
  tentativi. Vedere [Rate limit e utilizzo](/docs/api/rate-limits-and-usage).

Leggere sempre l’oggetto `errors` quando è presente: indica esattamente che cosa
correggere.