A busy sender can use its request budget before all its messages are queued. Reading the remaining quota lets it slow down before more calls are refused.
How does Bird decide my limit?
Bird applies a base rate, any plan increase and then any override for the relevant group. An override replaces the other values.
Related endpoints share a group. Exhausting a send group does not itself exhaust the separate groups used to read status or manage webhooks.
The scope of each budget depends on the operation:
| Group | Who shares the budget? |
|---|---|
| Product sends | All credentials in the organization for that product. |
| Management reads, lists and writes | Requests from the same acting credential within the organization. |
| Unauthenticated login or password reset | Requests from the same client IP. |
Unauthenticated limits use fixed thresholds. See the rate limits guide for the groups assigned to individual endpoints.
Send limits count requests, not recipients. A batch request can queue several messages. Its group may have a different quota.
Compare the live quotas and the number of recipients you can group before switching endpoints. A batch containing one recipient may provide no throughput gain.
How do I read the response headers?
Read RateLimit-Policy for the quota and window, then RateLimit for the remaining requests and time until reset.
For example:
RateLimit-Policy: "email_send";q=1000;w=60
RateLimit: "email_send";r=842;t=35This example allows 1,000 requests per 60-second window. It has 842 requests remaining, with 35 seconds until reset.
The numbers illustrate the headers. They are not a promised quota. Read the values returned to your client.
| Field | Meaning |
|---|---|
| Quoted name | The group the policy applies to. |
q | Requests allowed per window. |
w | Window length in seconds. |
r | Requests remaining. |
t | Seconds until reset, not a timestamp. |
A response can carry more than one policy. Account for every applicable policy when scheduling the next request.
What does a rate-limit failure return?
An exhausted API limit returns 429 Too Many Requests with Retry-After in seconds. The rate-limit headers identify the exhausted group. Its remaining quota is r=0.
The error envelope includes these fields:
{
"error": {
"type": "rate_limit_error",
"code": "E01003",
"name": "RateLimited"
}
}Match the type or code in your handler. The human-readable message can change without changing the recovery action.
How should my client handle a 429?
Wait for Retry-After, then retry with a bounded backoff policy. Keep the same idempotency key when repeating the same write.
Coordinate workers using the same group budget. A worker's last response cannot account for requests that other workers have submitted since then.
Slow down as the remaining quota falls. Retain the retry path for concurrent traffic. Pacing reduces failures but cannot guarantee that no call receives a 429.
Bird SDKs handle 429 retries and Retry-After. They do not coordinate a shared queue across all your processes.
If the quota remains too low for the workload, contact Bird about an override. Creating more keys does not increase an organization-wide send limit.
Has a rate-limited request done any work?
Bird rejects a rate-limited request before doing the requested work. That rejection does not consume its idempotency key. Retry it with the same key after waiting.
The limiter allows requests through if it cannot evaluate the limit. A problem evaluating quotas therefore does not itself produce a 429.
Keep idempotency handling for other failures too. A server error or lost response can occur after a write has begun.
In short
Read the quota from responses.
The applicable limit depends on the group, plan and any override. A fixed number can become wrong.
Coordinate senders that share a quota.
Send limits apply across an organization, so separate keys do not create separate send budgets.
Wait before retrying a 429.
Retry-Aftergives the delay in seconds. Bound your retries. Preserve the idempotency key for the same write.Treat headers as shared state.
Remaining requests can be consumed by other workers, so pacing reduces rate-limit failures without eliminating them.