Uma requisição pode chegar ao servidor mesmo quando sua aplicação nunca recebe a resposta. Sua integração precisa de uma política para essa incerteza antes de começar a retentar envios.
Os SDKs REST da Bird fornecem esse tratamento de requisições para TypeScript, Python, Go e PHP. Os pacotes Swift e Kotlin servem assinaturas Realtime em vez da REST API.
O que um Bird SDK trata?
O SDK cuida da mecânica repetível de requisições, incluindo retentativas, roteamento e proteção contra duplicatas.
Para uma operação mutante, ele gera um Idempotency-Key e o mantém entre retentativas internas. Isso permite que Bird reconheça a mesma operação após uma resposta perdida.
Ele retenta falhas transitórias com backoff que respeita Retry-After. Um 429, portanto, resulta em uma espera antes da próxima tentativa. Falhas de autenticação e validação ainda exigem que sua aplicação corrija a causa.
Helpers de listagem buscam páginas sucessivas conforme você itera. O roteamento regional seleciona o host a partir do prefixo da sua chave. Helpers de webhook verificam o corpo bruto da requisição antes de retornar o evento decodificado.
Sua aplicação ainda precisa rejeitar ações de negócio duplicadas. Ela também precisa recuperar seu próprio trabalho inacabado. Idempotência explica o limite entre retentativas de requisição e garantias da aplicação.
E se não houver método tipado para a minha operação?
Use os métodos de verbo HTTP do SDK para chamar um endpoint público sem um método tipado dedicado.
Esses métodos mantêm o tratamento de requisições, incluindo retentativas e seleção de região. Você fornece o caminho e o payload a partir da referência da API.
A ausência de um método tipado não torna uma operação indisponível. Mudar o método de chamada não altera quais endpoints sua credencial pode acessar.
Por exemplo, rotacione uma chave API por meio de uma sessão CLI ou MCP autenticada, ou use o dashboard. O servidor CLI ou MCP precisa de autorização de uma pessoa com api_keys:write. Um serviço que possui apenas uma chave API não pode executá-la.
Quando devo chamar a HTTP diretamente?
Chame diretamente quando os SDKs disponíveis não se encaixarem na sua linguagem, runtime ou política de dependências.
Você também pode usar uma requisição direta para inspecionar um endpoint antes de escolher uma biblioteca cliente. Bird usa a mesma HTTP API pública para ambas as abordagens.
Gere um cliente a partir da especificação OpenAPI se quiser modelos gerados em outra linguagem. Verifique o comportamento em runtime separadamente, porque os geradores diferem no que implementam.
Para requisições diretas, selecione o host da região da sua chave. Reutilize uma chave de idempotência entre retentativas de uma operação. Siga os cursores de paginação. Verifique as assinaturas de webhook recebidas sobre o corpo inalterado.
Defina limites de retentativa e timeout para que uma dependência com falha não mantenha uma requisição da aplicação aberta indefinidamente.
Como as retentativas afetam meu timeout?
Uma retentativa pode fazer a chamada total durar mais que o timeout de uma única tentativa.
Os SDKs permitem duas retentativas por padrão, dando a uma chamada até três tentativas. TypeScript, Python e Go usam um timeout padrão de 60 segundos por tentativa. Três tentativas com timeout esgotado podem, portanto, consumir cerca de três minutos antes de adicionar as esperas entre retentativas.
PHP usa o timeout configurado no cliente HTTP que você injeta. Defina-o lá para que a requisição tenha uma duração limitada.
Ajuste o orçamento de retentativas junto com qualquer deadline externo. O guia de conceitos do SDK descreve os nomes de configuração e as substituições por chamada para cada linguagem.
Não adicione um loop de retentativas ilimitado ao redor do SDK. Chamadas SDK separadas geram chaves separadas, a menos que você forneça uma chave de idempotência estável para toda a operação.
Qual integração devo escolher?
Escolha a menor quantidade de tratamento de requisições que sua aplicação precisa gerenciar.
- Bird SDK: sua linguagem é suportada e as dependências se encaixam no seu runtime.
- Método de verbo SDK: a operação é pública, mas não possui um método tipado dedicado.
- Cliente gerado: você precisa de outra linguagem ou de suas próprias convenções de geração.
- HTTP direta: você quer controlar dependências e implementar a política de requisições por conta própria.
Em resumo
SDKs cuidam da mecânica repetitiva de requisições.
Eles gerenciam chaves de idempotência, retentativas, roteamento regional, paginação e verificação de webhooks. Sua aplicação continua responsável pelas regras de negócio.
A falta de um método tipado não precisa bloquear você.
Use os métodos de verbo HTTP do SDK para operações públicas fora da superfície tipada. O tratamento de requisições continua valendo.
Mantenha uma chave única entre retentativas da aplicação.
Chamadas SDK separadas geram chaves de idempotência separadas, a menos que você forneça a chave da operação.
Planeje cada tentativa.
Duas retentativas são habilitadas por padrão. TypeScript, Python e Go aplicam timeout a cada tentativa separadamente. PHP usa o timeout do cliente HTTP.