Código de motivo estable
Un código de error estable se utiliza en la lógica del cliente, los informes y el enrutamiento automático de consultas.
Documentación / Errores de API
Gestión de errores de API
Un modelo unificado para respuestas, códigos de error, fallos temporales, resultados desconocidos, diagnóstico y recuperación segura en integraciones de iGaming.
HTTP
resultado de la solicitud
Códigos
motivo claro
Reintento
acción segura
Trazabilidad
diagnóstico de la solicitud
Ciclo de gestión de errores
De la respuesta de la API a la recuperación
01
Determinar el tipo de resultado
Compruebe el estado HTTP, el código de motivo, la categoría del error y el estado de la operación.
02
Guardar datos para la investigación
Registre los identificadores de la solicitud y la operación, el endpoint, la hora, la referencia del proveedor y parámetros seguros.
03
Elegir una acción segura
Corrija los datos, detenga la operación, reintente tras una pausa o compruebe el estado actual.
04
Recuperar y verificar
Evite duplicados, concilie los resultados, notifique a los equipos responsables y cierre la causa raíz.
Resumen
Un error debe explicar la causa y la siguiente acción
Una respuesta HTTP 400 o 500 por sí sola no es suficiente. Una API fiable devuelve un código de motivo estable, vincula la respuesta a un identificador de solicitud y permite saber si hay que corregir los datos, detener la operación, reintentar la solicitud o comprobar su estado por separado.
Acción predecible
La categoría del error indica si la solicitud puede reintentarse y qué datos deben modificarse.
Correlación para diagnóstico
Los identificadores de solicitud, operación y proveedor vinculan los registros del cliente con los sistemas internos y el soporte.
Estructura del error
Estructura recomendada de la respuesta de error
La respuesta debe ser compacta, estable y apta para el procesamiento automatizado sin exponer la implementación interna ni datos sensibles.
Código de error
Un identificador estable del motivo que no cambia al editar el mensaje explicativo.
Descripción
Una explicación breve y segura sin código interno, consultas a bases de datos, secretos ni detalles innecesarios.
ID de solicitud
Un identificador único para localizar la operación en los registros y contactar con soporte.
Datos adicionales
Un estado permitido, límite, estado actual o motivo seguro de rechazo.
Reintentable
Una indicación explícita de un error temporal que no elimina la protección frente a duplicados de la operación.
Pausa antes del reintento
Un retraso recomendado en segundos o una cabecera HTTP para límites de frecuencia y falta de disponibilidad temporal.
Errores de campos
Una lista de campos problemáticos con un código de motivo, la ruta del valor y una explicación segura.
Referencia a la documentación
Un enlace permanente o identificador de sección que describe la causa y cómo corregirla.
Categorías de errores
Principales categorías de errores
El estado HTTP indica la clase general del resultado, mientras que el código interno identifica la causa concreta y la acción permitida.
Error de validación de entrada
Formato no válido, campo obligatorio ausente, valor no compatible, precisión incorrecta del importe o estructura de solicitud no válida.
Error de autenticación
Token, clave de API, firma, marca temporal de la solicitud o nonce ausente, caducado o no válido.
Permisos insuficientes
El cliente se reconoce, pero no dispone del rol, la marca, el mercado o el permiso necesarios para la acción.
Objeto no encontrado
Un jugador, pago, ronda, comprobación KYC, proveedor u otro objeto no existe o no está disponible para el cliente.
Conflicto de estado
La versión o el estado del objeto ha cambiado, o el identificador de la operación ya se ha utilizado con parámetros diferentes.
Incumplimiento de una regla de negocio
Saldo insuficiente, límite superado, jugador bloqueado, mercado prohibido o transición de estado no válida.
Demasiadas solicitudes
Se ha superado el número de solicitudes permitido para el cliente, método, rol u operación crítica.
Proveedor no disponible
El servicio externo no está disponible, responde lentamente o no acepta operaciones temporalmente.
Error interno
Un error inesperado de la plataforma sin exponer detalles internos, pero con un identificador para el diagnóstico.
Reintentos y recuperación
Reintento de solicitud y resultado desconocido
Un reintento solo es seguro después de identificar el tipo de error y comprobar si la operación original ya pudo haberse completado.
01
Comprobar si se permite el reintento
Los errores de datos, permisos y reglas de negocio suelen requerir corregir la solicitud en lugar de volver a enviarla.
02
Mantener la misma clave de operación
Reintentar una operación financiera, de juego u otra operación crítica no debe crear un resultado nuevo.
03
Aumentar la pausa entre intentos
Los intervalos aumentan progresivamente, respetan el retraso indicado por el servidor y limitan el número total de intentos.
04
Detener y escalar para revisión
Una vez agotados todos los intentos, la operación se registra como incompleta y se envía a revisión manual o conciliación.
No recibir respuesta no significa que la operación haya fallado
Si la conexión se interrumpe después de enviar una solicitud, el resultado puede seguir siendo desconocido. Antes de reintentar, compruebe el estado mediante el identificador de la operación o espere una notificación de confianza.
Diagnóstico y control
Registros, identificadores, métricas y alertas
El diagnóstico debe reconstruir la ruta de la solicitud entre la plataforma, el adaptador y el proveedor externo sin almacenar datos sensibles innecesarios.
Contexto de investigación
Identificadores de solicitud, correlación, operación y proveedor externo.
Endpoint, método HTTP, entorno, cliente, hora y duración de la respuesta.
Estado HTTP, código de error, número de intentos y estado final.
Campos sensibles enmascarados, cabeceras seguras y resultado de la validación de la firma.
Supervisión y alertas
Tasa de errores por método, proveedor, cliente y categoría de motivo.
Aumento de respuestas lentas, errores HTTP 5xx, firmas no válidas y eventos de límite de frecuencia.
Número de reintentos, operaciones con resultado desconocido y tareas de recuperación.
Alertas con umbrales, responsables y reglas de escalado.
Pruebas
Qué probar en el entorno de pruebas
El entorno de pruebas debe reproducir cada categoría importante de error y confirmar el comportamiento correcto del cliente, los reintentos y los controles.
Errores de validación de entrada
Campos ausentes, tipos no válidos, valores no compatibles, precisión del importe y varios errores simultáneos.
Acceso y permisos
Clave no válida, token caducado, firma incorrecta, rol no autorizado, IP bloqueada y nonce reutilizado.
Sin respuesta y resultado desconocido
Fallo de conexión antes del envío, después de aceptar la operación y durante la recepción de la respuesta final.
Límite de frecuencia
HTTP 429, pausa recomendada, solicitudes simultáneas y recuperación tras finalizar el límite.
Errores del proveedor
Falta de disponibilidad, mantenimiento, respuesta no válida, notificación retrasada y estado contradictorio.
Reintento y parada de protección
Limitar el número de intentos, aumentar las pausas, detener temporalmente las solicitudes, realizar una recuperación controlada y escalar manualmente.
Lista de comprobación previa al lanzamiento
Una integración de producción se lanza después de validar la estructura de errores, el comportamiento del cliente, la protección frente a duplicados y el diagnóstico.
Todos los errores devuelven un código de motivo estable y un identificador de solicitud.
Los detalles de los errores no exponen secretos ni la implementación interna.
Las categorías de errores temporales y permanentes están documentadas.
Una operación crítica reintentada utiliza la misma clave de idempotencia.
Un resultado desconocido se gestiona comprobando el estado o recibiendo una notificación de confianza.
Están configurados los registros, las métricas, las alertas, una cola de recuperación y las reglas de escalado.
¿Necesita estandarizar los errores de API?
Envíenos sus respuestas HTTP actuales, códigos de error, reglas de reintento y escenarios problemáticos. APIACE ayudará a definir un modelo de errores unificado, una recuperación segura y un enfoque de control.