A request can reach the server even when your application never receives the response. Your integration needs a policy for that uncertainty before it starts retrying sends.
Bird's REST SDKs provide that request handling for TypeScript, Python, Go and PHP. Swift and Kotlin packages serve Realtime subscriptions instead of the REST API.
What does a Bird SDK handle?
The SDK handles repeatable request mechanics, including retries, routing and duplicate protection.
For a mutating operation, it generates an Idempotency-Key and keeps it across internal retries. This lets Bird recognize the same operation after a lost response.
It retries transient failures with backoff that honors Retry-After. A 429 therefore leads to a wait before another attempt. Authentication and validation failures still need your application to correct their cause.
List helpers fetch successive pages as you iterate. Region routing selects the host from your key's prefix. Webhook helpers verify the raw request body before returning the decoded event.
Your application still needs to reject duplicate business actions. It also needs to recover its own unfinished work. Idempotency explains the boundary between request retries and application guarantees.
What if there is no typed method for my operation?
Use the SDK's HTTP verb methods to call a public endpoint without a dedicated typed method.
These methods retain request handling, including retries and region selection. You supply the path and payload from the API reference.
An absent typed method does not make an operation unavailable. Changing the calling method does not change which endpoints your credential can access.
For example, rotate an API key through a signed-in CLI or MCP session, or use the dashboard. The CLI or MCP server needs authorization from a person with api_keys:write. A service holding only an API key cannot perform it.
When should I call HTTP directly?
Call directly when the available SDKs do not fit your language, runtime or dependency policy.
You can also use a direct request to inspect an endpoint before choosing a client library. Bird uses the same public HTTP API for both approaches.
Generate a client from the OpenAPI specification if you want generated models in another language. Check its runtime behavior separately, because generators differ in what they implement.
For direct requests, select the host for your key's region. Reuse an idempotency key across retries of one operation. Follow pagination cursors. Verify incoming webhook signatures over the unchanged body.
Set retry and timeout limits so a failing dependency cannot keep an application request open indefinitely.
How do retries affect my timeout?
A retry can make the total call last longer than one attempt's timeout.
The SDKs allow two retries by default, giving a call up to three attempts. TypeScript, Python and Go default to a 60-second timeout per attempt. Three timed-out attempts can therefore consume about three minutes before adding retry waits.
PHP uses the timeout configured on the HTTP client you inject. Set it there so the request has a bounded duration.
Adjust the retry budget alongside any outer deadline. The SDK concepts guide describes configuration names and per-call overrides for each language.
Do not add an unlimited retry loop around the SDK. Separate SDK calls generate separate keys unless you supply one stable idempotency key for the whole operation.
Which integration should I choose?
Choose the smallest amount of request handling your application needs to own.
- Bird SDK: your language is supported and its dependencies fit your runtime.
- SDK verb method: the operation is public but lacks a dedicated typed method.
- Generated client: you need another language or your own generation conventions.
- Direct HTTP: you want to control dependencies and implement the request policy yourself.
In short
SDKs handle repeated request plumbing.
They manage idempotency keys, retries, regional routing, pagination and webhook verification. Your application still owns its business rules.
A missing typed method need not block you.
Use the SDK's HTTP verb methods for public operations outside its typed surface. Request handling still applies.
Keep one key across application retries.
Separate SDK calls generate separate idempotency keys unless you supply the key for the operation yourself.
Budget for every attempt.
Two retries are enabled by default. TypeScript, Python and Go time out each attempt separately. PHP uses its HTTP client's timeout.