Errori

Ogni richiesta Bird API fallita restituisce la stessa risposta di errore JSON, annidata sotto una chiave di primo livello error. Questa è una risposta reale a una richiesta di invio con corpo vuoto:

{
  "error": {
    "type": "validation_error",
    "code": "E01001",
    "name": "ValidationError",
    "message": "Request has 1 validation error.",
    "doc_url": "https://bird.com/docs/api/errors/E01001",
    "request_id": "req_01ky7q3hckecgv6d7jpq865532",
    "details": [{ "param": "body", "message": "missing properties 'from', 'to'" }]
  }
}

Lo status HTTP deriva dal type. Gli errori client usano 400 per richieste malformate, 401 o 403 per errori di accesso, 402 per la fatturazione e 404 per risorse mancanti. Usano 409 per i conflitti, 412 per precondizioni non soddisfatte, 422 per errori di validazione e regole di business e 429 per la limitazione delle richieste. Gli errori lato Bird usano 5xx. Lo status identifica la categoria; la risposta di errore spiega cosa è successo.

I campi della risposta di errore

Usa type per la gestione approssimativa e code per la gestione specifica, mai message. Un client tipico fa switch su type (riprovare su rate_limit_error, mostrare validation_error all'utente, allertare qualcuno su internal_error) e confronta singoli valori code solo per i pochi errori che gestisce in modo specifico.

Codici come E04012 sono volutamente opachi. Per tradurne uno in linguaggio comprensibile, leggi il message dell'errore, poi apri il suo doc_url: ogni codice ha una pagina che spiega cosa è andato storto e cosa fare. Il catalogo completo si trova nel riferimento errori.

Errori di validazione: un codice, molti dettagli

La validazione a livello di campo non prevede un codice separato per ogni combinazione campo-errore. La maggior parte dei problemi sui campi è E01001 ValidationError. Il message di primo livello indica cosa non va e param identifica il campo. Un array details elenca ogni problema a livello di campo come {param, message}, così come l'errore di invio catturato elenca le proprietà mancanti. Una proprietà di contatto è identificata dalla sua chiave sotto data, ad esempio data.plan. Alcuni errori di validazione indicano un singolo campo in param e non includono details, quindi leggi details quando è presente. Le stringhe message possono cambiare e vanno solo visualizzate. Usa param per mappare i problemi ai campi del form.

Indicazioni per il recupero: rimedio e passi successivi

Gli errori con una correzione nota la includono nella risposta di errore. Questa è una risposta reale a una chiamata webhooks effettuata con una chiave API priva dello scope richiesto:

{
  "error": {
    "type": "permission_error",
    "code": "E02035",
    "name": "InsufficientScope",
    "message": "This request requires the \"webhooks:read\" scope, which your credential has not been granted.",
    "param": "webhooks:read",
    "doc_url": "https://bird.com/docs/api/errors/E02035",
    "request_id": "req_01ky7q4665emc9tw1pxkptaqwq",
    "remediation": "Re-authenticate with a credential that has been granted the required scope, then retry."
  }
}

remediation è una frase destinata a un essere umano o al log di un agente; next, quando presente, elenca le operazioni API che risolvono l'errore nell'ordine in cui provarle (verificare un dominio, poi riprovare l'invio). Agenti e CLI possono eseguire next direttamente; i client interattivi possono mostrare remediation così com'è.

Gestire bene gli errori

• Riprova 429 e 5xx, nient'altro per default. Rispetta Retry-After sulla limitazione delle richieste (vedi Limitazione delle richieste), usa il backoff esponenziale su 5xx e invia un Idempotency-Key per rendere sicuri i retry delle richieste mutanti.
• Registra code, name e request_id insieme. Il codice è ciò che cercherai nella documentazione e nei tuoi log; il request ID è ciò di cui ha bisogno il supporto.
• Tollera nuovi codici e tipi. Nuovi codici di errore vengono rilasciati regolarmente con la crescita dei prodotti e l'enum type occasionalmente acquisisce un valore. Scrivi il tuo handler con un branch di default ragionevole anziché un match esaustivo.

Passi successivi

• Riferimento errori: il catalogo completo degli errori, una pagina per codice
• Idempotenza: retry sicuri per le richieste mutanti
• Limitazione delle richieste: header dei limiti e indicazioni sul backoff