A failed request may need a delay, a corrected field or a different credential. Bird's error response provides fields your handler can use to choose that action.
Which error fields should I use?
Use type for broad handling and code for a specific recovery. Bird puts these fields inside a top-level error object.
The type groups failures such as validation, authentication and rate limiting. The code identifies the particular failure, such as E01001 for field validation.
Bird never renames or reuses a code. Retired codes remain reserved, so an existing code match keeps its meaning.
Display or log message, but do not match its text. Wording can change without changing the failure your handler needs to address.
The name makes logs readable. The doc_url links to the code's documentation. Log code, name and request_id together when an operation fails.
Which failures should I retry?
Retry temporary failures with a bounded policy. Fix input and credential problems before trying again. Check the specific code when one status can require different actions.
| Response | Default action |
|---|---|
429, E01003 | Wait for Retry-After, then retry. |
500, 502, 503 or 504 | Retry with increasing delays and an attempt limit. |
501 | Stop and check which operation the server supports. |
401 or 403 | Fix the credential or its permissions before retrying. |
| Field validation or invalid input | Correct the fields identified by the response. |
409, E01004 | Wait for the in-progress operation before retrying. |
409, E01005 | Correct the reuse of an idempotency key with different input. |
Keep the same idempotency key when retrying the same write. A timeout or server failure does not prove that the original operation did nothing.
Stop when the retry budget is exhausted and record the final error. Repeating an unchanged request indefinitely can hide a failure that needs intervention.
How do I handle field validation errors?
Read the details array on E01001 ValidationError and associate each entry with its param. Display that entry's message beside the affected field.
Do not parse those messages to identify the field or failure. Their wording can change, just like the top-level message.
A malformed request can instead return E01002 InvalidRequest. Use its documented recovery rather than assuming every input failure contains field-level details.
Can the response tell me how to recover?
Some errors include remediation, a human-readable next step, or next, an ordered list of operations to try.
Show the remediation when it helps the person correct the problem. For example, an authorization failure may require a credential with an additional scope.
An automated handler can use next to choose a recovery operation. It still needs that operation's inputs and permissions before executing it.
A vendor_code identifies a downstream failure, such as an SMTP response or payment decline. Consult that provider's code when the recovery depends on it.
What should happen for an unfamiliar code?
Keep a default branch that records the failure without crashing or retrying indefinitely. New codes and types can appear as the API grows.
Apply a known status-based retry policy where appropriate. Otherwise, stop and log the code with its request ID for investigation.
The errors guide documents the envelope. The error reference lists individual codes and their recovery guidance.
In short
Match codes rather than messages.
Bird never renames or reuses error codes, but human-readable messages can change.
Retry temporary failures with a limit.
Wait on rate limits and back off on temporary server failures. Keep the same idempotency key for a repeated write.
Read validation details.
E01001carries field problems indetails. Use eachparamto associate its message with the affected input.Keep a fallback for unknown errors.
Log unfamiliar codes and their request IDs so new failures do not break your handler.