# Gestión de errores avanzada Obtén más información sobre cómo identificar los errores en el nivel HTTP. En esta página se abordan dos temas avanzados de gestión de errores: - [Respuestas HTTP que representan errores](https://docs.stripe.com/error-low-level.md#errors-in-http) - [Idempotencia y reintentos](https://docs.stripe.com/error-low-level.md#idempotency) Es posible que esta información no se aplique a tu caso. Los [SDK](https://docs.stripe.com/sdks.md) 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](https://docs.stripe.com/error-handling.md) - [Códigos de error](https://docs.stripe.com/error-codes.md) ## 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](https://docs.stripe.com/error-handling.md). 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](https://docs.stripe.com/error-low-level.md#content-errors): Contenido no válido en la solicitud de API. - [Error de la red](https://docs.stripe.com/error-low-level.md#network-errors): Problemas de comunicación intermitente entre el cliente y el servidor. - [Error del servidor](https://docs.stripe.com/error-low-level.md#server-errors): 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](https://docs.stripe.com/error-low-level.md#status-codes) 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](https://docs.stripe.com/api/errors.md#errors-code) `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](https://docs.stripe.com/error-codes.md) 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 la red son producto 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, el cliente puede haber excedido el tiempo de espera cuando trataba de leer los servidores de Stripe o una interrupción prematura de la conexión puede haber impedido que llegue la respuesta de la API. Aunque *parezca* probable que el error de red se solucione después de corregir los problemas de conectividad, a veces puede haber otro 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. #### Ruby ```ruby 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](https://docs.stripe.com/webhooks.md) 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. > El resultado de las solicitudes que devuelven errores `500` debe tratarse como un error indeterminado. Si bien Stripe trata de conciliar su estado parcial de la mejor manera posible y activa [webhooks](https://docs.stripe.com/webhooks.md) para los objetos nuevos creados, no se garantizan resultados ideales. 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](https://docs.stripe.com/api/metadata.md) 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](https://stripe.com/blog/idempotency) 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](https://docs.stripe.com/api/idempotent_requests.md) 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](https://docs.stripe.com/api/idempotent_requests.md) 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](https://docs.stripe.com/api/idempotent_requests.md), 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 | | | | | 200 | Aceptada | Todo funcionó como se esperaba. | | 400 | Solicitud incorrecta | Solicitud inaceptable, a menudo debido a la falta de un parámetro obligatorio. | | 401 | No autorizado | No se proporcionó una clave de API válida. | | 402 | Error en la solicitud | Los parámetros eran válidos, pero se produjo un error en la solicitud. | | 403 | Prohibido | La clave API no tiene permisos para efectuar la solicitud. | | 409 | Conflicto | La solicitud entra en conflicto con otra solicitud (tal vez debido al uso de la misma clave [idempotente](https://docs.stripe.com/error-low-level.md#idempotency)). | | 424 | Dependencia externa fallida | No se pudo completar la solicitud debido a un error en una dependencia externa a Stripe. | | 429 | Demasiadas solicitudes | Se enviaron demasiadas solicitudes a la API en poco tiempo. [Recomendamos un retroceso exponencial de las solicitudes](https://docs.stripe.com/error-low-level.md#should-retry). | | 500, 502, 503, 504 | Errores del servidor | [Se produjo un error del lado de Stripe.](https://docs.stripe.com/error-low-level.md#server-errors) |