PDF Blocks
PrezziSupporto
Iniziare gratis
Aprire la pagina

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

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

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

{
  "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 e inviare la richiesta su HTTPS. Vedere Autenticazione.

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.

{
  "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 valido.

406: Accept non accettabile

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

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

Codici di stato riservati

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.

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

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

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

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

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

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.

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