Risposte di errore
Ogni richiesta fallita restituisce la stessa risposta di errore JSON sotto una chiave di primo livello error, con uno status HTTP che indica la categoria generale. Questa pagina descrive il contratto wire; per indicazioni su branching, nuovi tentativi e filosofia del catalogo dei codici, vedi Errori.
{
"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 della risposta di errore
| 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 testuale di un sistema a valle (un codice di risposta SMTP, un codice di rifiuto del pagamento), quando viene restituito. |
Mappatura degli status HTTP
Ogni type corrisponde a esattamente uno status HTTP, quindi lo status e la risposta di errore 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 che l'API pubblica di Bird restituisce, 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à | 24 codici, 2 ritirati |
E03xxx | Fatturazione e piani | 15 codici, 2 ritirati |
E04xxx | Invio e consegna e-mail | 87 codici, 3 ritirati |
E05xxx | Domini e DNS | 19 codici |
E06xxx | Webhook | 11 codici |
E07xxx | Wallet | 4 codici |
E08xxx | Gestione di spazi di lavoro e organizzazioni | 1 codice, 2 ritirati |
E10xxx | Quote | 16 codici, 2 ritirati |
E11xxx | Pool IP e IP dedicati | 4 codici, 1 ritirato |
E12xxx | Invio e consegna SMS | 62 codici, 5 ritirati |
E13xxx | Verify | 7 codici, 1 ritirato |
E14xxx | Numeri | 6 codici |
E15xxx | Invio e consegna WhatsApp | 75 codici |
E16xxx | Trust | 1 codice |
E17xxx | Caselle di posta per agenti | 16 codici, 2 ritirati |
E19xxx | Conformità della registrazione | 6 codici |
E20xxx | Asset e libreria multimediale | 15 codici |
E21xxx | Voce e trunking SIP | 20 codici, 9 ritirati |
E22xxx | Ricerca numero | 5 codici |
E23xxx | Realtime | 1 codice |
E24xxx | Competitive Insights | 6 codici |
E25xxx | Sendability | 5 codici, 1 ritirato |
E26xxx | eSIM | 19 codici |
E27xxx | Inbox Insights | 9 codici |
E28xxx | Apple Messages for Business | 48 codici, 2 ritirati |
E32xxx | Conferma operazioni | 6 codici |
E33xxx | Idoneità dell'organizzazione | 3 codici, 1 ritirato |
E34xxx | Connettori | 1 codice, 1 ritirato |
Correlati
- Concetti sugli errori: strategia di branching, dettagli di validazione e semantica di
vendor_code - Autenticazione: credenziali dietro
401e403 - Header Idempotency-Key: gli errori di conflitto
409e i nuovi tentativi sicuri - Limiti di frequenza: criteri, header e gestione di
429
Risorse correlate
Continua con la documentazione, le guide e gli esempi per questo argomento.