Formato degli errori e codici di errore API

Ogni risposta di errore dell’API ha lo stesso formato. Il tuo codice dovrebbe basarsi sul codice di errore nel campo error, non sul testo in message – il codice resta stabile, mentre il testo può cambiare e viene tradotto nella lingua dell’account.

#Struttura di una risposta di errore

{
  "error": "validation_failed",
  "message": "Some of the information provided is invalid. Please check and try again.",
  "details": [
    { "field": "title", "reason": "minLength", "message": "…" }
  ],
  "request_id": "6b1f0c2e-…"
}

error

Codice leggibile dalle macchine, per esempio not_found. Per la maggior parte degli errori si trova anche nell’header X-Error-Code – ma basati sul campo nel corpo.

message

Descrizione leggibile nella lingua dell’account: con una chiave API quella del proprietario del workspace, con un’app collegata quella della persona che l’ha collegata. Senza un token valido – per esempio con 401 dal controllo del token – la lingua segue Accept-Language, altrimenti è l’inglese. L’header Content-Language indica la lingua.

details

Presente solo quando c’è altro da dire. Per 422 dalla validazione dell’input, un elenco con field, reason e message per ogni problema; per 422 dalla logica di business e per tutti gli altri errori, un oggetto, per esempio con reason, retry_after_sec o un elenco di issues. Quando una dimensione viene superata contiene field, reason e limit, e per 413 request_too_large max_bytes e max_kb. Quindi verifica se details è un elenco.

request_id

L’ID della richiesta. Si trova anche nell’header X-Request-Id. Indicalo quando contatti l’assistenza.

Eccezioni: la risposta 429 rate_limited ha il campo retry_after_sec invece di details; con 429 e 403 insufficient_scope, request_id manca nel corpo. 401 dal controllo del token e 422 dal controllo dello schema non hanno l’header X-Error-Code, e con il controllo dello schema viene tradotto solo il message di primo livello; i testi all’interno di details restano in inglese. L’header X-Request-Id è sempre presente.

#I codici più importanti

#Leggere gli errori di input

Con 422 validation_failed, details elenca ogni problema separatamente: field è il percorso del campo (con barre per gli oggetti annidati, per esempio theme_config/button_style), reason è la regola violata, come required, minLength, maxLength, enum o additionalProperties. Con additionalProperties, il messaggio dice quali campi sono sconosciuti – spesso è un errore di battitura nel nome del campo.

#Gestione consigliata nel tuo codice

• 400, 413 e 422: non ripetere, correggi invece la richiesta
• 401 invalid_token: richiedi una volta un nuovo token e riprova
• 403: non ripetere; controlla lo scope, il piano o chi è autorizzato a farlo
• 404: controlla l’ID; dopo un’eliminazione è normale
• 409: ricarica lo stato e decidi se l’azione serve ancora
• 429: attendi quanto indicato da Retry-After, poi riprova – vedi Limiti di richieste
• 500 e 503: riprova qualche volta con pause crescenti