Messaggi di errore comuni
Quando una richiesta fallisce, Bird restituisce un errore strutturato con un codice leggibile dalla macchina, un messaggio, un link alla documentazione e un ID richiesta. Usa il codice nella logica del programma. Se hai bisogno di supporto, seleziona Feedback > Contact us e includi l'ID richiesta. Per il catalogo completo, consulta il riferimento errori API.
Errori di validazione
Indicano che Bird ha compreso la richiesta ma qualcosa al suo interno non è accettabile. L'errore elenca il campo o la condizione specifica in difetto.
Tutti i destinatari soppressi
Significato: ogni destinatario dell'invio è nella lista di soppressione, quindi non c'era nulla da recapitare e l'invio è stato rifiutato.
Causa probabile: stai inviando a indirizzi che in precedenza hanno generato un hard bounce, un reclamo o una disiscrizione, spesso segno che stai reinviando a una lista vecchia o non ripulita. Se solo alcuni destinatari sono soppressi, l'invio prosegue per gli altri e quelli soppressi risultano rifiutati; questo errore compare solo quando sono tutti soppressi.
Soluzione: verifica quali indirizzi sono soppressi e perché, poi rimuovili dalla tua lista. Perché la mia email è stata rifiutata? spiega come appaiono i rifiuti per soppressione, e la guida alle soppressioni illustra come gestire la lista.
Destinatario di onboarding non consentito
Significato: stai inviando dal dominio condiviso di onboarding di Bird a qualcuno che non è un membro verificato del tuo spazio di lavoro.
Causa probabile: il dominio condiviso recapita solo ai membri verificati dello spazio di lavoro e agli indirizzi di test sandbox.
Soluzione: per inviare email a destinatari reali, verifica il tuo dominio di invio, eliminando completamente la restrizione. Consulta Invio dal dominio condiviso per i vincoli e la procedura.
Campo mancante o non valido
Significato: un campo obbligatorio è assente, un valore non è valido oppure la richiesta combina campi incompatibili.
Causa probabile: la richiesta non corrisponde allo schema dell'operazione o combina campi incompatibili. I dettagli dell'errore identificano ogni campo in errore.
Soluzione: leggi i dettagli dell'errore e correggi i campi indicati.
Errori di limitazione delle richieste
Significato: la richiesta ha superato un limite di operazione, account o invio.
Causa probabile: un picco ha superato un limite di API, oppure un invio ha superato una quota come il tetto destinatari del dominio condiviso di onboarding.
Soluzione: segui la correzione indicata nell'errore e il valore Retry-After quando presente. Riprova i limiti transitori con backoff. Per il tetto giornaliero di onboarding, attendi il reset del giorno UTC o verifica il tuo dominio di invio. L'etichetta di salute email throttled è diagnostica e non causa un errore di limitazione delle richieste API.
Errori di autenticazione
Significato: Bird non ha potuto accettare le tue credenziali.
Causa probabile: una di queste tre situazioni, in ordine approssimativo di frequenza:
- Chiave API errata, scaduta o revocata: la chiave è digitata male, troncata, scaduta o non più attiva. Il segreto viene mostrato solo quando la chiave viene creata o ruotata.
- Chiave usata nella regione sbagliata: le chiavi API sono regionali e una chiave funziona solo con i server della propria regione. Se la chiave è stata creata in una regione e il tuo codice chiama un'altra, l'autenticazione fallisce. Il prefisso della chiave indica a quale regione appartiene.
- Chiave mancante: la richiesta non includeva alcuna credenziale, spesso a causa di una variabile d'ambiente vuota nell'ambiente in cui si verifica l'errore.
Soluzione: verifica che la chiave esista e sia attiva nella dashboard, che il tuo codice la stia inviando e che stai chiamando l'indirizzo regionale corrispondente alla chiave. In caso di dubbio, crea una nuova chiave e sostituiscila.
Dominio non verificato
Significato: il dominio di invio non ha completato la verifica, quindi Bird non può inviare da esso.
Causa probabile: i record DNS sono mancanti, ancora in propagazione o errati, oppure sono cambiati dopo la verifica. Consulta la checklist di verifica del dominio per le tempistiche previste.
Soluzione: apri la pagina del dominio nella dashboard per individuare il record mancante. Usa la checklist di verifica del dominio per correggerlo. Mentre il DNS propaga, usa il dominio condiviso di onboarding per gli invii di test.
Leggere qualsiasi errore incontrato
Filtra in base al codice di errore leggibile dalla macchina, perché i messaggi testuali possono cambiare. Registra l'ID richiesta. Se hai bisogno di supporto, seleziona Feedback > Contact us e includilo. Segui il link alla documentazione per la correzione specifica dell'errore.
Prossimi passi
- Riferimento errori API (il catalogo completo: ogni tipo di errore, codice e stato)
- Perché la mia email è stata rifiutata?: le ragioni dietro i rifiuti per singolo destinatario
- Perché la salute email mostra Throttled?: l'etichetta diagnostica di salute e i segnali che la determinano
- Invio dal dominio condiviso: i vincoli sui destinatari e il tetto giornaliero del dominio di onboarding
Risorse correlate
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.
Guarda la guidaWhat happens when someone opts outComprendi il concettoWhat is one-click unsubscribe, and how do I implement List-Unsubscribe?Esplora la funzionalitàEmail opt-outsSegui il percorso di apprendimentoOperate messaging reliably
Ottieni un brief di implementazione