Códigos de Respuesta del Sistema
Documentación completa de todos los códigos de respuesta utilizados en el sistema SwapBits, organizados por categorías y tipos de resultado.
Índice
- Formato General de Respuestas
- Códigos de Éxito (1xxx)
- Códigos de Operaciones Exitosas (2xxx)
- Códigos de Verificación (3xxx)
- Códigos de Error de Cliente (4xxx)
- Códigos de Error del Servidor (5xxx)
- Resumen por Categorías
Formato General de Respuestas
Respuesta Exitosa
{
"code": 1000,
"message": "Operación exitosa",
"data": {
// contenido específico del resultado
}
}
code: Identificador numérico del resultadomessage: Mensaje descriptivo en inglésdata: Contenido de la respuesta (solo en éxito)
Respuesta de Error
{
"code": 4001,
"message": "User not found.",
"id": "123-HN-I98"
}
code: Identificador numérico del errormessage: Descripción del errorid: Identificador único para trazabilidad y soporte
Códigos de Éxito (1xxx)
Registro y Autenticación
El proceso de registro de usuario se completó correctamente con todos los datos validados.
El usuario fue autenticado exitosamente. Proceder con verificación si es requerida.
Login exitoso con bypass de validaciones adicionales.
Gestión de Contraseña
Se envió correctamente el enlace de restablecimiento de contraseña al email del usuario.
La contraseña del usuario fue actualizada correctamente en el sistema.
Contraseña cambiada exitosamente por el usuario autenticado.
Gestión de Usuario
La cuenta del usuario fue eliminada completamente del sistema.
Los datos del perfil del usuario fueron actualizados correctamente.
La imagen del usuario fue subida y procesada correctamente.
Cuenta de usuario eliminada exitosamente mediante soft delete.
Autenticación de Dos Factores (2FA)
La autenticación de dos factores (2FA) fue desactivada para el usuario.
El código OTP proporcionado es válido y fue verificado correctamente.
Mensajería y Verificación
El mensaje o comunicación fue enviado exitosamente al destinatario.
Se envió correctamente el código de verificación al método configurado. También usado para sesión de cambio de contraseña creada.
Código de registro reenviado exitosamente al usuario.
Sistema PIN
PIN de seguridad configurado correctamente para el usuario.
PIN verificado correctamente, acceso autorizado.
PIN actualizado exitosamente.
Estado del PIN obtenido correctamente.
PIN habilitado correctamente para el usuario.
PIN deshabilitado correctamente.
Biometría
Dispositivo biométrico registrado exitosamente.
Dispositivo biométrico revocado correctamente.
Challenge biométrico generado exitosamente.
Códigos de Operaciones Exitosas (2xxx)
Transacciones y QR
La transacción financiera fue procesada y confirmada correctamente.
Solicitud de código QR procesada exitosamente.
Login mediante código QR aprobado correctamente.
OTP (One-Time Password)
Autenticación de dos factores generada exitosamente.
Estado de autenticación de dos factores obtenido correctamente.
Códigos de Verificación (3xxx)
Verificaciones Exitosas
El proceso de verificación de identidad (KYC) fue completado exitosamente.
La dirección de correo electrónico fue verificada y confirmada.
Códigos de Error de Cliente (4xxx)
Errores de Email
El formato del email proporcionado no es válido o contiene caracteres no permitidos.
Ya existe una cuenta registrada con esta dirección de correo electrónico.
El email del token no coincide con el email proporcionado.
El formato del email no cumple con los estándares RFC para direcciones de correo.
Errores de Usuario
No existe un usuario registrado con los datos proporcionados.
Usuario no encontrado en el sistema (usado en endpoints de cambio de contraseña).
Errores de Autenticación
La contraseña ingresada no coincide con la registrada para este usuario.
La contraseña no cumple con los requisitos mínimos de seguridad (longitud, caracteres, etc.).
Las credenciales proporcionadas (email y/o contraseña) son incorrectas.
El usuario tiene 2FA habilitado. Se requiere código de autenticación adicional.
La nueva contraseña no puede ser igual a la contraseña actual.
Se requiere código 2FA para usuarios que tienen habilitada la autenticación de dos factores.
Errores de Código/Token
El código de autenticación de dos factores ha expirado y debe solicitarse uno nuevo.
El token de verificación proporcionado no es válido o ha sido comprometido.
El código de verificación ingresado no coincide con el esperado. También usado para código 2FA inválido.
El código ha expirado o es inválido.
El token de sesión proporcionado no es válido o ha expirado.
Esta operación requiere un token de autenticación válido que no fue proporcionado.
Token de sesión no encontrado en el payload de la petición.
No se proporcionó token de autenticación o el token enviado no es válido.
El token de sesión expiró por inactividad. Se requiere nueva autenticación.
Se requiere token de validación. Debe ejecutarse el paso de solicitud primero.
Token de validación inválido o expirado (más de 5 minutos).
El token de validación no pertenece al usuario actual.
Errores de Sesión
La sesión no está autorizada para realizar esta operación.
Sesión expirada, se envió nuevo email de autorización.
Errores de Seguridad y Bloqueo
Dispositivo revocado previamente, requiere nueva autorización.
Nueva ubicación detectada, se requiere autorización por email.
Ubicación no autorizada, debe revisar email y autorizar primero.
Cuenta bloqueada temporalmente. También usado para PIN bloqueado por intentos fallidos.
Errores de PIN
El PIN no está configurado o no está activo para el usuario.
Errores de Datos
Faltan campos obligatorios en la petición. Verificar documentación del endpoint. También usado para datos inválidos.
Se requiere proporcionar una nueva contraseña.
Errores de QR y WebAuthn
Código QR inválido o expirado.
Challenge de WebAuthn no encontrado o expirado.
Códigos de Error del Servidor (5xxx)
Errores de Transacciones
Error interno al procesar la transacción. Contactar soporte con el ID del error.
Errores de Base de Datos
Error al guardar los datos del usuario en la base de datos. Problema interno del servidor.
Error interno al intentar eliminar la cuenta del usuario del sistema.
Error interno al actualizar los datos del usuario en el sistema.
Error interno al procesar o guardar la imagen del usuario.
Errores de KYC
El usuario debe completar el proceso de verificación de identidad antes de continuar.
Errores de Biometría
Challenge o firma biométrica inválida.
Challenge expirado o ya utilizado.
Dispositivo biométrico no registrado o revocado.
Errores Generales del Servidor
Error interno al obtener los datos del perfil del usuario.
Acceso no autorizado. El usuario no tiene permisos para realizar esta acción.
Implementación en Frontend
Guía de Manejo de Códigos
Reglas importantes:
codedefine el tipo de respuesta. Nunca dependas solo del textomessagepuede mostrarse al usuario o registrarse para análisisdatasolo está presente en respuestas exitosasidse usa únicamente en errores y debe guardarse para trazabilidad
TypeScript/JavaScript
interface ApiResponse<T = any> {
code: number;
message: string;
data?: T;
id?: string;
}
const handleApiResponse = <T>(response: ApiResponse<T>) => {
if (response.code >= 1000 && response.code < 4000) {
// Respuesta exitosa (códigos 1xxx-3xxx)
showSuccessNotification(response.message);
return { success: true, data: response.data };
}
else if (response.code >= 4000 && response.code < 5000) {
// Error de cliente/validación (códigos 4xxx)
showErrorNotification(response.message);
logClientError(response.id, response.code);
return { success: false, error: response.message };
}
else if (response.code >= 5000) {
// Error de servidor (códigos 5xxx)
showErrorNotification('Error interno del servidor');
logServerError(response.id, response.code, response.message);
return { success: false, error: 'Error interno' };
}
};
// Ejemplo de uso
const loginUser = async (email: string, password: string) => {
const response = await apiCall('/auth/login', { email, password });
return handleApiResponse(response);
};
Códigos Especiales de Atención
Código 4014 - 2FA Requerido
Este código NO es un error, sino una indicación de que se requiere un paso adicional de autenticación. El frontend debe redirigir al usuario a la pantalla de verificación 2FA.
Código 1010 - Múltiples Usos
El código 1010 se usa tanto para "código de verificación enviado" como para "sesión de cambio de contraseña creada". Verificar el contexto del endpoint para determinar el significado exacto.
Códigos de Validación Token
Los códigos 4031, 4032, 4033 son específicos del flujo de cambio de contraseña:
- 4031: Token no proporcionado (ejecutar Paso 1)
- 4032: Token expirado (más de 5 minutos)
- 4033: Token no pertenece al usuario actual
Resumen por Categorías
Rangos de Códigos
Códigos de Éxito:
- 1000-1999: Operaciones exitosas generales (registro, autenticación, gestión)
- 2000-2999: Operaciones específicas exitosas (transacciones, QR, OTP)
- 3000-3999: Verificaciones exitosas (KYC, email)
Códigos de Error:
- 4000-4999: Errores del cliente (validación, autenticación, autorización)
- 5000-5999: Errores del servidor (base de datos, procesamiento interno)
Estadísticas
| Categoría | Rango | Total |
|---|---|---|
| Registro y Autenticación | 1000-1011 | 3 códigos |
| Gestión de Contraseña | 1002-1013 | 3 códigos |
| Gestión de Usuario | 1004-1012 | 4 códigos |
| 2FA | 1007-1008 | 2 códigos |
| Mensajería | 1009-1014 | 3 códigos |
| Sistema PIN | 1015-1020 | 6 códigos |
| Biometría | 1021-1023 | 3 códigos |
| Transacciones y QR | 2000-2002 | 3 códigos |
| OTP | 2003-2004 | 2 códigos |
| Verificaciones | 3000-3001 | 2 códigos |
| Errores Email | 4000-4020 | 4 códigos |
| Errores Usuario | 4001-4040 | 2 códigos |
| Errores Autenticación | 4007-4034 | 6 códigos |
| Errores Código/Token | 4003-4033 | 11 códigos |
| Errores Sesión | 4024-4027 | 2 códigos |
| Errores Seguridad | 4025-4030 | 4 códigos |
| Errores PIN | 4031 | 1 código |
| Errores Datos | 4006-4017 | 2 códigos |
| Errores QR/WebAuthn | 4018-4019 | 2 códigos |
| Errores Servidor | 5000-5012 | 10 códigos |
Total de códigos documentados: 67 códigos
- Códigos de éxito: 29 códigos (1xxx-3xxx)
- Códigos de error cliente: 28 códigos (4xxx)
- Códigos de error servidor: 10 códigos (5xxx)
Última actualización: 18 de octubre de 2025