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
| Campo | Sempre presente | Descrizione |
|---|---|---|
| type | Sì | Categoria generale per il branching: un enum chiuso (auth_error, validation_error, rate_limit_error, ...). |
| code | Sì | Identificatore opaco e stabile corrispondente a E\d{5}. Univoco, mai rinominato, mai riutilizzato; il valore canonico su cui fare match. |
| name | Sì | Slug leggibile (ValidationError) per la leggibilità dei log. Sempre accoppiato con code, mai un sostituto. |
| message | Sì | Descrizione leggibile. Non stabile: visualizzala o registrala nei log, non eseguirne il parsing. |
| doc_url | Sì | Link stabile alla pagina di documentazione di questo code. |
| request_id | Sì | ID di correlazione, restituito anche come header di risposta X-Request-Id. Citalo nelle richieste di supporto. |
| param | No | Il campo incriminato, quando un singolo campo è la causa dell'errore. |
| details | No | Errori di validazione per campo come oggetti {param, message}, dove param è un percorso puntato come to[0].email. Presente solo nelle risposte validation_error. |
| vendor_code | No | Codice 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.
| Status | type | Significato |
|---|---|---|
| 400 | bad_request_error | La richiesta era malformata: un body non parsabile o un header non valido (ad esempio, un Idempotency-Key errato). |
| 401 | auth_error | La richiesta conteneva credenziali mancanti, non valide o revocate. Vedi Autenticazione. |
| 402 | billing_error | La richiesta richiede un metodo di pagamento, un saldo o un piano che l'organizzazione non possiede. Vedi Fatturazione e utilizzo. |
| 403 | permission_error | Le credenziali sono valide, ma non autorizzate a eseguire questa richiesta. Vedi Autenticazione. |
| 404 | not_found_error | Nessuna route corrisponde a questo percorso, oppure la risorsa non esiste in questo spazio di lavoro. Vedi Regioni. |
| 409 | conflict_error | La richiesta è in conflitto con lo stato corrente della risorsa, inclusi conflitti di idempotenza (E01004, E01005). Vedi Idempotenza. |
| 410 | gone_error | La risorsa esisteva ma è stata rimossa permanentemente. |
| 412 | precondition_error | Una precondizione per questa richiesta non è stata soddisfatta. |
| 413 | payload_too_large_error | Il body della richiesta supera la dimensione massima consentita. |
| 421 | misdirected_error | La richiesta ha raggiunto una regione che non può servirla. Vedi Regioni. |
| 422 | delivery_error | Il messaggio è stato accettato come richiesta ma non può essere recapitato all'indirizzo specificato. |
| 422 | validation_error | Il body della richiesta è stato analizzato, ma uno o più valori non sono validi. |
| 425 | too_early_error | La richiesta è arrivata prima di poter essere elaborata. |
| 429 | rate_limit_error | Un gruppo di limitazione delle richieste è esaurito per questo spazio di lavoro. Vedi Limiti di frequenza. |
| 499 | client_closed_request_error | La connessione si è chiusa prima che la risposta fosse pronta, di solito perché il chiamante ha smesso di attendere. |
| 500 | internal_error | Qualcosa è fallito dal nostro lato durante l'elaborazione della richiesta. Vedi Idempotenza. |
| 501 | not_implemented_error | L'endpoint è dichiarato nel API ma non ancora implementato. |
| 503 | service_unavailable_error | Una 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;
}from bird import APIStatusError, RateLimitError, ValidationError
try:
client.email.send(
from_={"email": "onboarding@messagebird.dev", "name": "Bird"},
to=["delivered@messagebird.dev"],
subject="Hello from Bird",
text="My first Bird email.",
)
except RateLimitError as err:
print("rate limited; retry after", err.retry_after)
except ValidationError as err:
print(err.status_code, err.details)
except APIStatusError as err:
print(err.status_code, err.code, err.request_id)if err != nil {
var rle *bird.RateLimitError
var ve *bird.ValidationError
var ae *bird.APIError
switch {
case errors.As(err, &rle):
fmt.Println("rate limited; retry after", rle.RetryAfter)
case errors.As(err, &ve):
for _, d := range ve.Details {
fmt.Printf("%s: %s\n", d.Param, d.Message)
}
case errors.As(err, &ae):
fmt.Printf("API error %s (status %d, request %s)\n", ae.Code, ae.StatusCode, ae.RequestID)
default:
log.Print(err) // transport: *bird.ConnectionError or *bird.TimeoutError
}
}try {
$bird->email->send(
from: 'Bird <onboarding@messagebird.dev>',
to: ['delivered@messagebird.dev'],
subject: 'Hello from Bird',
html: '<p>My first Bird email.</p>',
);
} catch (ApiException $e) {
// The server returned an error response. $status is the HTTP status, $type
// the coarse category, $errorCode the stable E##### code.
echo $e->status, ' ', $e->errorCode ?? $e->type ?? 'error';
} catch (ConnectionException $e) {
// All retry attempts failed, so no HTTP response is available.
echo 'transport error: ', $e->getMessage();
}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.
| Intervallo | Area | Codici |
|---|---|---|
| E01xxx | Infrastruttura | 30 codici, 2 ritirati |
| E02xxx | Auth e identità | 9 codici, 2 ritirati |
| E03xxx | Fatturazione e piani | 12 codici |
| E04xxx | Invio e recapito e-mail | 67 codici, 3 ritirati |
| E05xxx | Domini e DNS | 19 codici |
| E06xxx | Webhook | 7 codici |
| E07xxx | Wallet | 4 codici |
| E10xxx | Quote | 9 codici, 2 ritirati |
| E11xxx | Pool IP e IP dedicati | 4 codici, 1 ritirato |
| E12xxx | Invio e recapito SMS | 49 codici, 5 ritirati |
| E13xxx | Verify | 7 codici, 1 ritirato |
| E14xxx | Numeri | 5 codici |
| E15xxx | Invio e recapito WhatsApp | 49 codici |
| E16xxx | Trust | 1 codice |
| E17xxx | Caselle agente | 14 codici, 2 ritirati |
| E19xxx | Conformità registrazione | 4 codici |
| E21xxx | Voce e trunking SIP | 16 codici, 7 ritirati |
| E22xxx | Ricerca numero | 4 codici |
| E23xxx | Realtime | 1 codice |
| E24xxx | Competitive Insights | 6 codici |
| E25xxx | Sendability | 5 codici, 1 ritirato |
| E27xxx | Inbox Insights | 5 codici |
| E28xxx | Apple Messages for Business | 18 codici, 2 ritirati |
| E32xxx | Conferma operazioni | 6 codici |
Correlati
- Concetti sugli errori: strategia di branching, dettagli di validazione e semantica di vendor_code
- Autenticazione: credenziali dietro 401 e 403
- Header Idempotency-Key: gli errori di conflitto 409 e i retry sicuri
- Limiti di frequenza: criteri, header e gestione di 429
Risorse correlate
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.
Comprendi il concettoShould I use a Bird SDK or call the API directly?Segui il percorso di apprendimentoBuild your first integrationGuida all'implementazioneSend your first email
Ottieni un brief di implementazione