Una solicitud fallida puede necesitar una espera, un campo corregido o una credencial diferente. La respuesta de error de Bird proporciona campos que tu handler puede usar para elegir esa acción.
¿Qué campos de error debo usar?
Usa type para un manejo general y code para una recuperación específica. Bird coloca estos campos dentro de un objeto error de nivel superior.
El tipo agrupa fallos como validación, autenticación y limitación de solicitudes. El código identifica el fallo concreto, por ejemplo E01001 para validación de campos.
Bird nunca renombra ni reutiliza un código. Los códigos retirados permanecen reservados, así que una coincidencia existente conserva su significado.
Muestra o registra message, pero no compares su texto. La redacción puede cambiar sin que cambie el fallo que tu handler debe atender.
El name hace los logs legibles. El doc_url enlaza a la documentación del código. Registra code, name y request_id juntos cuando una operación falle.
¿Qué fallos debo reintentar?
Reintenta fallos temporales con una política acotada. Corrige problemas de entrada y credenciales antes de volver a intentar. Revisa el código específico cuando un mismo estado puede requerir acciones diferentes.
| Respuesta | Acción predeterminada |
|---|---|
429, E01003 | Espera Retry-After y luego reintenta. |
500, 502, 503 o 504 | Reintenta con intervalos crecientes y un límite de intentos. |
501 | Detente y verifica qué operación admite el servidor. |
401 o 403 | Corrige la credencial o sus permisos antes de reintentar. |
| Validación de campos o entrada inválida | Corrige los campos indicados por la respuesta. |
409, E01004 | Espera a que termine la operación en curso antes de reintentar. |
409, E01005 | Corrige la reutilización de una clave de idempotencia con entrada diferente. |
Mantén la misma clave de idempotencia al reintentar la misma escritura. Un timeout o un fallo del servidor no demuestra que la operación original no hizo nada.
Detente cuando el presupuesto de reintentos se agote y registra el error final. Repetir una solicitud sin cambios indefinidamente puede ocultar un fallo que necesita intervención.
¿Cómo manejo los errores de validación de campos?
Lee el array details en E01001 ValidationError y asocia cada entrada con su param. Muestra el message de esa entrada junto al campo afectado.
No analices esos mensajes para identificar el campo o el fallo. Su redacción puede cambiar, igual que el mensaje de nivel superior.
Una solicitud mal formada puede devolver E01002 InvalidRequest. Usa su recuperación documentada en lugar de asumir que todo fallo de entrada contiene detalles a nivel de campo.
¿Puede la respuesta indicarme cómo recuperarme?
Algunos errores incluyen remediation, un paso siguiente legible, o next, una lista ordenada de operaciones a intentar.
Muestra la remediación cuando ayude a la persona a corregir el problema. Por ejemplo, un fallo de autorización puede requerir una credencial con un alcance adicional.
Un handler automatizado puede usar next para elegir una operación de recuperación. Aun así necesita las entradas y permisos de esa operación antes de ejecutarla.
Un vendor_code identifica un fallo de un servicio externo, como una respuesta SMTP o un rechazo de pago. Consulta el código de ese proveedor cuando la recuperación dependa de él.
¿Qué debe pasar con un código desconocido?
Mantén una rama por defecto que registre el fallo sin provocar un crash ni reintentar indefinidamente. Pueden aparecer nuevos códigos y tipos a medida que API crece.
Aplica una política de reintento conocida basada en el estado cuando corresponda. De lo contrario, detente y registra el código con su ID de solicitud para investigación.
La guía de errores documenta la respuesta de error. La referencia de errores lista los códigos individuales y su orientación de recuperación.
En resumen
Compara códigos, no mensajes.
Bird nunca renombra ni reutiliza códigos de error, pero los mensajes legibles pueden cambiar.
Reintenta fallos temporales con un límite.
Espera en los límites de solicitudes y aumenta el intervalo en fallos temporales del servidor. Mantén la misma clave de idempotencia en una escritura repetida.
Lee los detalles de validación.
E01001incluye problemas de campo endetails. Usa cadaparampara asociar su mensaje con el campo afectado.Mantén un respaldo para errores desconocidos.
Registra los códigos desconocidos y sus ID de solicitud para que los fallos nuevos no rompan tu handler.