A request ID is an identifier for one call to an API, generated by the server, meant for tracing that call in the provider's own systems. It is the thing support asks for, and the reason to log it is that you cannot go back and get it once the call is over.
On Bird it arrives two ways at once: as request_id inside the error envelope, and as the X-Request-Id response header on the response itself.
When should I actually use it?
When you are asking about one specific attempt rather than about a message.
That distinction is what makes it useful and what makes it easy to misuse. A request ID identifies a call: one POST, one response. If you retried three times, that is three request IDs, and the one worth quoting is the attempt that behaved wrongly. Quoting the id of the successful retry when the problem was in the first attempt sends support to the wrong record.
So the shape that works in a support conversation is the specific one: this request ID, at this time, returned this code, and I expected something else.
What should I log?
Three fields together, and it is worth being deliberate because two of them are useless without the third.
code, name and request_id. The code is what you will search for in the documentation and in your own history when it happens again. The name makes the log readable. The request ID is the only part support can trace, and it is the part you cannot reconstruct.
Log the id on successes too, not just failures. The calls you most want traced are often the ones that returned 202 and then did something you did not expect, and by then the header is gone.
How is it different from my own correlation ID?
It answers a different question, and Bird has a separate place for yours.
A request ID is ours: it identifies a call inside our systems and means nothing in yours. Your correlation ID is the reverse, and the way to carry it is in metadata or tags on the send. Those ride through to the webhook events, which also carry the message and recipient identifiers, so you can reconcile an event against your own records without a second lookup.
That is the division worth setting up before you need it: our id for asking us about one call, your id for joining our events to your data.
Which identifier does what?
Four things get called IDs on a messaging platform and they are not interchangeable. Reaching for the wrong one is a common way to build something that almost works.
| Identifier | Whose | What it is for |
|---|---|---|
request_id | Ours | Tracing one exact API call, in a support request |
Idempotency-Key | Yours | Making a retry of a mutation safe |
webhook-id | Ours | Deduplicating a webhook delivery that arrives twice |
metadata or tags | Yours | Joining our events back to your own records |
The two of ours identify different things: a request ID is one call inbound to us, a webhook-id is one delivery outbound to you, and a single message produces one of the first and several of the second. Batches shift that ratio: one POST /v1/email/batches call queues up to 100 messages under a single request ID, so quote the message ID too when you are asking about one recipient of a batch.
And an idempotency key is the one that must be stable across attempts rather than unique per attempt, which is the opposite of a request ID. Generating a fresh one per retry defeats it entirely, and that mistake is easy to make if you have been thinking of them as the same kind of thing.
Errors documents the envelope the request ID arrives in, and idempotency covers the key that is yours to generate.