Documentation
Sign inGet started
Inizia ora
Guide
Riferimento API
SDK e CLI
Knowledge Base
Changelog

Common error messages

When a request to Bird fails, you get back a structured error: a stable error code you can match on, a human-readable message, and a link to the documentation for that exact error. So the error itself is always your first clue. This page translates the errors people hit most often into plain language — what each means, why it usually happens, and how to fix it. For the complete catalog with every code, see the API error reference.

Validation errors

These mean Bird understood your request but something in it isn't acceptable. The error lists the specific field or condition at fault.

All recipients suppressed

What it means: every recipient on your send is on your suppression list, so there was nothing left to deliver and the send was refused.
Likely cause: you're sending to addresses that previously hard-bounced, complained, or unsubscribed — often a sign you're re-mailing an old or uncleaned list. If only some recipients are suppressed, the send goes through for the rest and the suppressed ones show as rejected; this error only appears when it's all of them.
The fix: check which addresses are suppressed and why, and remove them from your own list. Why was my email rejected? explains how suppression rejections show up, and the suppressions guide covers managing the list.

Onboarding recipient not allowed

What it means: you're sending from Bird's shared onboarding domain to someone who isn't a verified member of your workspace.
Likely cause: the shared domain is a test-and-first-send capability — it only delivers to you and your teammates (plus the sandbox test addresses), by design, to protect the domain's reputation for everyone sharing it.
The fix: to email real recipients, verify your own sending domain — that removes the restriction entirely. See Sending from the shared domain for the guardrails and the way out.

Missing or invalid field

What it means: a required field is absent, or a value doesn't validate — a malformed address, an empty subject, a field that isn't supported yet.
Likely cause: usually a small mistake in the request your code builds. The error's details name each failing field and what's wrong with it.
The fix: read the field list in the error and correct the named fields — no guessing needed.

Rate-limit errors

What it means: you've made more requests in the current window than your plan allows. This is temporary by definition.
Likely cause: either a burst of send requests exceeded your per-minute limit, or — if you're on the shared onboarding domain — you've hit its daily recipient cap (by default 50 recipients per organization per day, resetting the next day).
The fix: wait and retry — the error tells you how long. For per-minute limits, the wait is seconds; spreading requests out or batching sends avoids it entirely, and higher plan tiers raise the ceiling. For the onboarding daily cap, the real fix is verifying your own domain, which removes the cap. If sending is being slowed for reputation reasons rather than request volume, that's a different mechanism — see Why was I throttled or paused?.

Authentication errors

What it means: Bird couldn't accept your credentials.
Likely cause: one of three things, in rough order of frequency —
  • Wrong or revoked API key: the key is mistyped, truncated, or was revoked (keys revoked by a teammate are a classic). Keys are only shown in full once, at creation.
  • Key used against the wrong region: API keys are regional, and a key only works against its own region's servers. If your key was created in one region and your code calls another, authentication fails — the key prefix tells you which region it belongs to.
  • Missing key: the request didn't include credentials at all, often an environment variable that's empty in the environment that's failing.
The fix: confirm the key exists and is active in your dashboard, that your code is sending it, and that you're calling the regional address that matches the key. If in doubt, create a fresh key and swap it in.

Domain not verified

What it means: you tried to send from a domain that hasn't completed verification, so Bird can't send as it yet.
Likely cause: the domain's DNS records aren't published yet, haven't propagated, or have a small mistake — or the domain was verified before and its DNS has since changed. DNS propagation alone can take from minutes up to a day or two.
The fix: open the domain's page in the dashboard to see exactly which record is outstanding. Domain verification delays has the checklist for the cases where a record genuinely needs fixing. While you wait, the shared onboarding domain keeps test sends working.

Reading any error you meet

Every Bird error carries the same three things: a stable code (safe to match on in your code — it never changes), a human message (display or log it, but don't parse it), and a docs link straight to the page for that error. It also includes a request ID — quote that in any support conversation and we can find the exact request.

Related pages