Sign inGet Started

Risposte di errore

Ogni richiesta fallita restituisce lo stesso envelope JSON sotto una chiave di primo livello error, con uno status HTTP che indica la categoria generale. Questa pagina è il contratto wire; per indicazioni su branching, ripetizione dei tentativi e filosofia del catalogo dei codici, vedi Errori.
Esempio di codice
{
  "error": {
    "type": "validation_error",
    "code": "E01001",
    "name": "ValidationError",
    "message": "Request validation failed.",
    "doc_url": "https://bird.com/docs/api/errors/E01001",
    "request_id": "req_01krdgeqcxet5s7t44vh8rt9mg",
    "details": [
      { "param": "contact_id", "message": "this field is reserved and not yet supported" },
      { "param": "topic_id", "message": "this field is reserved and not yet supported" }
    ]
  }
}

Campi dell'envelope

CampoSempre presenteDescrizione
typeSìCategoria generale per il branching: un enum chiuso (auth_error, validation_error, rate_limit_error, ...).
codeSìIdentificatore opaco e stabile corrispondente a E\d{5}. Univoco, mai rinominato, mai riutilizzato; il valore canonico su cui fare match.
nameSìSlug leggibile (ValidationError) per la leggibilità dei log. Sempre accoppiato con code, mai un sostituto.
messageSìDescrizione leggibile. Non stabile: visualizzala o registrala nei log, non eseguirne il parsing.
doc_urlSìLink stabile alla pagina di documentazione di questo code.
request_idSìID di correlazione, restituito anche come header di risposta X-Request-Id. Citalo nelle richieste di supporto.
paramNoIl campo incriminato, quando un singolo campo è la causa dell'errore.
detailsNoErrori di validazione per campo come oggetti {param, message}, dove param è un percorso puntato come to[0].email. Presente solo nelle risposte validation_error.
vendor_codeNoCodice verbatim da un sistema a valle (un codice di risposta SMTP, un codice di rifiuto pagamento) quando vale la pena agire.

Mappatura degli status HTTP

Ogni type corrisponde a esattamente uno status HTTP, quindi status ed envelope non sono mai in disaccordo.
StatustypeSignificato
400bad_request_errorLa richiesta era malformata: un body non parsabile o un header non valido (ad esempio, un Idempotency-Key errato).
401auth_errorLa richiesta conteneva credenziali mancanti, non valide o revocate. Vedi Autenticazione.
402billing_errorLa richiesta richiede un metodo di pagamento, un saldo o un piano che l'organizzazione non possiede. Vedi Fatturazione e utilizzo.
403permission_errorLe credenziali sono valide, ma non autorizzate a eseguire questa richiesta. Vedi Autenticazione.
404not_found_errorNessuna route corrisponde a questo percorso, oppure la risorsa non esiste in questo spazio di lavoro. Vedi Regioni.
409conflict_errorLa richiesta è in conflitto con lo stato corrente della risorsa, inclusi conflitti di idempotenza (E01004, E01005). Vedi Idempotenza.
410gone_errorLa risorsa esisteva ma è stata rimossa permanentemente.
412precondition_errorUna precondizione per questa richiesta non è stata soddisfatta.
413payload_too_large_errorIl body della richiesta supera la dimensione massima consentita.
421misdirected_errorLa richiesta ha raggiunto una regione che non può servirla. Vedi Regioni.
422delivery_errorIl messaggio è stato accettato come richiesta ma non può essere recapitato all'indirizzo specificato.
422validation_errorIl body della richiesta è stato analizzato, ma uno o più valori non sono validi.
425too_early_errorLa richiesta è arrivata prima di poter essere elaborata.
429rate_limit_errorUn gruppo di limitazione delle richieste è esaurito per questo spazio di lavoro. Vedi Limiti di frequenza.
499client_closed_request_errorLa connessione si è chiusa prima che la risposta fosse pronta, di solito perché il chiamante ha smesso di attendere.
500internal_errorQualcosa è fallito dal nostro lato durante l'elaborazione della richiesta. Vedi Idempotenza.
501not_implemented_errorL'endpoint è dichiarato nel API ma non ancora implementato.
503service_unavailable_errorUna dipendenza di questa richiesta è temporaneamente non disponibile.

Gestione degli errori negli SDK

Ogni SDK mappa l'envelope sul modello di errore nativo del proprio linguaggio e include ogni campo dell'envelope (type, code, message, doc_url, request_id, ...) nel valore dell'errore.
import { BirdRateLimitError, BirdValidationError, BirdAPIError } from "@messagebird/sdk";

try {
  await bird.email.send({
    from: { email: "onboarding@messagebird.dev", name: "Bird" },
    to: ["delivered@messagebird.dev"],
    subject: "Hello from Bird",
    html: "<p>My first Bird email.</p>",
  });
} catch (err) {
  if (err instanceof BirdRateLimitError) console.log(`rate limited; retry in ${err.retryAfter}s`);
  else if (err instanceof BirdValidationError) console.error(err.details);
  else if (err instanceof BirdAPIError) console.error(err.code, err.requestId);
  else throw err;
}

Catalogo degli errori

Tutti i codici di errore restituiti dall'API Bird API pubblica, suddivisi in una pagina per intervallo di codici. Ogni pagina di intervallo elenca i propri codici e ogni codice ha una pagina dedicata con la causa e le azioni da intraprendere. Il doc_url in ogni risposta di errore rimanda direttamente alla pagina di quel codice.
IntervalloAreaCodici
E01xxxInfrastruttura30 codici, 2 ritirati
E02xxxAuth e identità9 codici, 2 ritirati
E03xxxFatturazione e piani12 codici
E04xxxInvio e recapito e-mail67 codici, 3 ritirati
E05xxxDomini e DNS19 codici
E06xxxWebhook7 codici
E07xxxWallet4 codici
E10xxxQuote9 codici, 2 ritirati
E11xxxPool IP e IP dedicati4 codici, 1 ritirato
E12xxxInvio e recapito SMS49 codici, 5 ritirati
E13xxxVerify7 codici, 1 ritirato
E14xxxNumeri5 codici
E15xxxInvio e recapito WhatsApp49 codici
E16xxxTrust1 codice
E17xxxCaselle agente14 codici, 2 ritirati
E19xxxConformità registrazione4 codici
E21xxxVoce e trunking SIP16 codici, 7 ritirati
E22xxxRicerca numero4 codici
E23xxxRealtime1 codice
E24xxxCompetitive Insights6 codici
E25xxxSendability5 codici, 1 ritirato
E27xxxInbox Insights5 codici
E28xxxApple Messages for Business18 codici, 2 ritirati
E32xxxConferma operazioni6 codici

Correlati