Gestión de errores avanzada

En esta página se abordan dos temas avanzados de gestión de errores:

• Respuestas HTTP que representan errores
• Idempotencia y reintentos

Es posible que esta información no se aplique a tu caso. Los SDK oficiales de Stripe pueden manejar la mayoría de los datos relacionados con HTTP y los reintentos. Si usas una biblioteca de clientes, empieza aquí:

• Gestión de errores
• Códigos de error

Errores en HTTP

Incluso cuando falla una llamada a la API, nuestras bibliotecas de cliente ponen a disposición la información de error generando una excepción o devolviendo un valor de error. Pero si no usas una biblioteca de cliente, o si surge una situación inusual, es posible que necesite detalles de bajo nivel sobre las respuestas HTTP y cuándo las emitimos.

Desde el punto de vista de HTTP, los errores se dividen en tres categorías principales:

• Error de contenido: Contenido no válido en la solicitud de API.
• Error de la red: Problemas de comunicación intermitente entre el cliente y el servidor.
• Error del servidor: Un problema en los servidores de Stripe.

Cada tipo de error requiere un enfoque y una semántica de idempotencia diferentes. Se proporciona una lista completa de códigos de respuesta y su significado al final de esta página.

Errores de contenido

Los errores de contenido son el resultado del contenido no válido de una solicitud de API. Devuelven una respuesta HTTP con un código de respuesta 4xx. Por ejemplo, los servidores de API pueden devolver un 401 si proporcionaste una clave de API no válida, o un 400 si faltaba un parámetro obligatorio. Las integraciones deben corregir la solicitud original y volver a intentarlo. Según el tipo de error del usuario (por ejemplo, el rechazo de una tarjeta), es posible que se pueda gestionar el problema mediante programación. En estos casos, incluye un campo code para ayudar a la integración a reaccionar correctamente. Consulta los códigos de error para más información.

En caso de una operación POST con una clave de idempotencia, siempre que la ejecución haya sido iniciada por un método de API, los servidores de API de Stripe almacenarán los resultados de la solicitud independientemente de cuáles hayan sido. Una solicitud que devuelve un error 400, volverá a enviar el mismo error 400 si le sigue una nueva solicitud con la misma clave de idempotencia. Para que el resultado sea correcto, debes generar una nueva clave de idempotencia al modificar la solicitud original. Respecto de esta operación, hay algunas advertencias. Por ejemplo, una solicitud con un código de error 429 por límite de frecuencia, puede obtener un resultado diferente con la misma clave de idempotencia porque los limitadores de frecuencia se ejecutan antes que la capa de idempotencia de la API. Lo mismo se aplica a un error 401 por omisión de una clave de API o a la mayoría de los errores 400 por envío de parámetros no válidos. Aun así, la estrategia más segura en lo que respecta a errores 4xx es generar siempre una nueva clave de idempotencia.

Errores de la red

Los errores de red son el resultado de problemas de conectividad entre el cliente y el servidor. Devuelven errores de bajo nivel, como excepciones de socket o tiempo de espera. Por ejemplo, es posible que el cliente agote el tiempo de espera al intentar leer los servidores de Stripe, o que nunca se reciba una respuesta de la API debido a una interrupción prematura de la conexión. Si bien un error de red parece que se solucionará después de resolver los problemas de conectividad, a veces hay otro tipo de error oculto en el problema intermitente.

En este tipo de errores, es donde se ve más claramente el valor de las claves de idempotencia y los reintentos de solicitud. Cuando surgen problemas de comunicación intermitente, los clientes suelen quedarse sin saber si el servidor recibió o no la solicitud. Para obtener una respuesta definitiva, deben reintentar esas solicitudes con las mismas claves de idempotencia y los mismos parámetros hasta recibir alguna respuesta del servidor. El envío de la misma idempotencia con diferentes parámetros produce un error que indica que la nueva solicitud no coincide con la original.

La mayoría de las bibliotecas de clientes pueden generar claves de idempotencia y solicitudes de reintentos automáticamente, pero para que lo hagan, es necesario configurarlas. Realizan su primer reintento rápidamente después del primer error, y los reintentos posteriores en un calendario de retroceso exponencial, con la suposición de que un solo error suele ser una ocurrencia aleatoria, pero un patrón de errores repetidos probablemente representa un problema crónico.

Stripe.max_network_retries = 2

Errores del servidor

Los errores del servidor son consecuencia de un problema con los servidores de Stripe. Devuelven una respuesta HTTP con un código de error 5xx. Estos errores son los más difíciles de manejar y trabajamos para que sean lo menos frecuentes posible, pero una buena integración los gestiona cuando surgen.

Como ocurre con los errores de usuario, la capa de idempotencia almacena el resultado de las mutaciones POST que generan errores del servidor (específicamente los errores 500 que son errores internos del servidor), de manera que hacer reintentos con la misma clave de idempotencia suele arrojar el mismo resultado. El cliente puede reintentar la solicitud con una nueva clave de idempotencia, pero no lo aconsejamos porque la clave original puede haber producido efectos secundarios.

Debes tratar el resultado de una solicitud 500 como indeterminado. El momento más probable para observar uno es durante un incidente de producción y, en general, durante la rectificación de dicho incidente. Los ingenieros de Stripe examinan las solicitudes con errores e intentan conciliar de forma adecuada los resultados de cualquier mutación que dé lugar a 500. Si bien la respuesta almacenada en caché de idempotencia a esas solicitudes no cambiará, intentaremos activar webhooks para los objetos nuevos creados como parte de la conciliación de Stripe. La naturaleza exacta de cualquier cambio retroactivo en el sistema depende en gran medida del tipo de solicitud. Por ejemplo, si al crear un cargo se obtiene un error 500, pero detectamos que la información se envió a una red de pago, intentaremos anularlo. Si no es así, intentaremos revertirlo. Si esto no resuelve el problema, es posible que aún veas solicitudes con un error 500 que producen efectos secundarios visibles para el usuario.

Para permitir que tu integración maneje el rango más amplio de 500, configura controladores de webhooks para recibir objetos de eventos que nunca recibes en las respuestas normales de API. Una técnica para establecer referencias cruzadas de estos nuevos objetos con los datos del estado local de una integración consiste en enviar un identificador local con los metadatos al crear nuevos recursos con la API. Ese identificador aparece en el campo de metadatos de un objeto que sale a través de un webhook, incluso si el webhook se genera más tarde como parte de la conciliación.

Idempotencia

Idempotencia es un principio de diseño de API web definido como la capacidad de aplicar la misma operación varias veces sin cambiar el resultado más allá del primer intento. Hace que sea seguro reintentar las solicitudes de API en algunas situaciones, en particular, cuando la primera solicitud no recibe respuesta debido a un error de la red. Dado que se puede esperar una cierta cantidad de errores intermitentes, los clientes necesitan una forma de conciliar las solicitudes fallidas con un servidor, y la idempotencia proporciona un mecanismo para eso.

La mayoría de las bibliotecas de clientes pueden generar claves de idempotencia y solicitudes de reintentos automáticamente, pero es necesario configurarlas. Para tener un control más preciso de los reintentos, genera claves de idempotencia y escribe tu propia lógica para los reintentos.

Solicitudes GET y DELETE

La API de Stripe garantiza la idempotencia de las solicitudes GET y DELETE, por lo que siempre es seguro volver a intentarlas.

Solicitudes POST

La inclusión de una clave de idempotencia hace que las solicitudes POST sean idempotentes, lo que le indica a la API que lleve un registro necesario para evitar la duplicación de operaciones. Los clientes pueden reintentar de forma segura las solicitudes que incluyen una clave de idempotencia siempre que la segunda solicitud se produzca en el transcurso de las 24 horas posteriores a la recepción de la clave por primera vez (las claves caducan fuera del sistema después de 24 horas). Por ejemplo, si una solicitud para crear un objeto no responde debido a un error de conexión de red, un cliente puede reintentar la solicitud con la misma clave de idempotencia para garantizar que no se cree más de un objeto.

Cómo enviar claves de idempotencia

Las claves de idempotencia se envían en el encabezado Idempotency-Key. Úsalas para todas las solicitudes POST a la API de Stripe. La mayoría de las bibliotecas oficiales de clientes pueden enviarlas automáticamente, siempre y cuando estén configuradas para enviar reintentos.

Si decides enviar claves de idempotencia manualmente, asegúrate de que los tokens utilizados sean lo suficientemente singulares como para identificar, como mínimo, una sola operación dentro de tu cuenta durante las últimas 24 horas. Existen dos estrategias comunes para generar claves de idempotencia:

• Usa un algoritmo que genere un token con suficiente aleatoriedad, como UUID v4.
• Deriva la clave de un objeto adjunto por el usuario, como el ID de un carrito de compras. Esto proporciona una forma relativamente sencilla de protegerse contra los envíos duplicados.

Para identificar una respuesta ya ejecutada que se esté reproduciendo desde el servidor, busca el encabezado Idempotent-Replayed: true.

El encabezado Stripe-Should-Retry

Una biblioteca de cliente no siempre puede determinar con certeza si debe hacer reintentos basándose únicamente en un código de estado o el contenido del cuerpo de la respuesta. La API responde con el encabezado Stripe-Should-Retry cuando tiene información adicional que indica que se puede reintentar la solicitud.

• Si Stripe-Should-Retry está establecido en true, el cliente debe reintentar la solicitud. Los clientes deberán esperar un poco (probablemente en función del calendario de retroceso exponencial) antes de hacer la siguiente solicitud para no sobrecargar a la API.
• Si Stripe-Should-Retry está establecido en false, el cliente no debe reintentar la solicitud porque no tendrá un efecto adicional.
• Si Stripe-Should-Retry no está definido en la respuesta, la API no podrá determinar si se puede o no reintentar la solicitud. Los clientes deben recurrir a otras propiedades de la respuesta (como el código de estado) para tomar una decisión.

Los mecanismos de reintento integrados en las bibliotecas de clientes de Stripe respetan la opción Stripe-Should-Retry de forma automática. Si estás usando uno de ellos, no necesitas manejarlo manualmente.

Referencia del código de estado HTTP