Una solicitud puede llegar al servidor aunque tu aplicación nunca reciba la respuesta. Tu integración necesita una política para esa incertidumbre antes de empezar a reintentar envíos.
Los SDKs REST de Bird proporcionan ese manejo de solicitudes para TypeScript, Python, Go y PHP. Los paquetes de Swift y Kotlin sirven para suscripciones Realtime en lugar de la REST API.
¿Qué maneja un Bird SDK?
El SDK maneja la mecánica repetible de las solicitudes, incluidos reintentos, enrutamiento y protección contra duplicados.
Para una operación que modifica datos, genera un Idempotency-Key y lo mantiene en los reintentos internos. Esto permite a Bird reconocer la misma operación tras una respuesta perdida.
Reintenta fallos transitorios con retroceso que respeta Retry-After. Por lo tanto, un 429 genera una espera antes del siguiente intento. Los fallos de autenticación y validación siguen necesitando que tu aplicación corrija su causa.
Los helpers de listado obtienen páginas sucesivas a medida que iteras. El enrutamiento de región selecciona el host a partir del prefijo de tu clave. Los helpers de webhook verifican el cuerpo crudo de la solicitud antes de devolver el evento decodificado.
Tu aplicación aún necesita rechazar acciones de negocio duplicadas. También necesita recuperar su propio trabajo sin terminar. Idempotencia explica el límite entre los reintentos de solicitud y las garantías de la aplicación.
¿Qué pasa si no existe un método tipado para mi operación?
Usa los métodos de verbo HTTP del SDK para llamar a un endpoint público sin un método tipado dedicado.
Estos métodos conservan el manejo de solicitudes, incluidos reintentos y selección de región. Proporcionas la ruta y el payload desde la referencia de API.
La ausencia de un método tipado no hace que una operación deje de estar disponible. Cambiar el método de llamada no cambia a qué endpoints puede acceder tu credencial.
Por ejemplo, rota una clave API mediante una sesión CLI o MCP con inicio de sesión, o usa el dashboard. El servidor CLI o MCP necesita autorización de una persona con api_keys:write. Un servicio que solo posee una clave API no puede realizar esta operación.
¿Cuándo debería llamar a HTTP directamente?
Llama directamente cuando los SDKs disponibles no se ajusten a tu lenguaje, runtime o política de dependencias.
También puedes usar una solicitud directa para inspeccionar un endpoint antes de elegir una biblioteca cliente. Bird usa la misma HTTP API pública para ambos enfoques.
Genera un cliente a partir de la especificación OpenAPI si quieres modelos generados en otro lenguaje. Verifica su comportamiento en runtime por separado, porque los generadores difieren en lo que implementan.
Para solicitudes directas, selecciona el host de la región de tu clave. Reutiliza una clave de idempotencia en los reintentos de una misma operación. Sigue los cursores de paginación. Verifica las firmas de webhooks entrantes sobre el cuerpo sin modificar.
Configura límites de reintento y timeout para que una dependencia fallida no pueda mantener abierta una solicitud de la aplicación indefinidamente.
¿Cómo afectan los reintentos a mi timeout?
Un reintento puede hacer que la llamada total dure más que el timeout de un solo intento.
Los SDKs permiten dos reintentos por defecto, lo que da a una llamada hasta tres intentos. TypeScript, Python y Go usan un timeout por defecto de 60 segundos por intento. Tres intentos agotados pueden consumir entonces unos tres minutos antes de sumar las esperas de reintento.
PHP usa el timeout configurado en el cliente HTTP que inyectas. Configúralo ahí para que la solicitud tenga una duración acotada.
Ajusta el presupuesto de reintentos junto con cualquier plazo externo. La guía de conceptos de SDK describe los nombres de configuración y las sobrecargas por llamada para cada lenguaje.
No añadas un bucle de reintentos ilimitado alrededor del SDK. Llamadas SDK separadas generan claves separadas, a menos que proporciones una clave de idempotencia estable para toda la operación.
¿Qué integración debería elegir?
Elige la menor cantidad de manejo de solicitudes que tu aplicación necesite gestionar por sí misma.
- Bird SDK: tu lenguaje está soportado y sus dependencias se ajustan a tu runtime.
- Método de verbo SDK: la operación es pública pero carece de un método tipado dedicado.
- Cliente generado: necesitas otro lenguaje o tus propias convenciones de generación.
- HTTP directa: quieres controlar las dependencias e implementar la política de solicitudes tú mismo.
En resumen
Los SDKs manejan la mecánica repetitiva de las solicitudes.
Gestionan claves de idempotencia, reintentos, enrutamiento regional, paginación y verificación de webhooks. Tu aplicación sigue siendo responsable de sus reglas de negocio.
La falta de un método tipado no tiene por qué bloquearte.
Usa los métodos de verbo HTTP del SDK para operaciones públicas fuera de su superficie tipada. El manejo de solicitudes sigue aplicándose.
Mantén una sola clave en los reintentos de la aplicación.
Llamadas SDK separadas generan claves de idempotencia separadas, a menos que tú proporciones la clave para la operación.
Presupuesta cada intento.
Dos reintentos están habilitados por defecto. TypeScript, Python y Go agotan el tiempo de cada intento por separado. PHP usa el timeout de su cliente HTTP.