Saltar al contenido principal

Códigos de Error

Referencia de códigos HTTP, mensajes específicos por proveedor (Manteca/Bridge), estructura estándar de errores y buenas prácticas de manejo y monitoreo.

🚨 Cómo leer esta sección

Los endpoints del servicio bancario suelen devolver errores con statusCode y un message descriptivo. Esta guía agrupa códigos HTTP, mensajes frecuentes, estructuras de respuesta y recomendaciones para frontend/backend.

📋 Códigos HTTP Comunes​

Tabla de códigos HTTP

CódigoDescripciónCuándo se usa
200OKÉxito en la operación
201CreatedRecurso creado exitosamente
400Bad RequestError en los datos proporcionados
401UnauthorizedToken JWT inválido o faltante
403ForbiddenAcceso denegado
404Not FoundRecurso no encontrado
409ConflictRecurso ya existe
500Internal Server ErrorError interno del servidor

🔴 Mensajes de Error Específicos​

Manteca​

Usuarios y Autenticación

  • "Solo usuarios argentinos pueden crear cuenta en Manteca"
  • "Datos KYC no encontrados"
  • "El usuario no tiene una cuenta activa en Manteca"
  • "Usuario no encontrado en Manteca"

Trading y Órdenes

  • "Monedas no soportadas en el par X: Y"
  • "El código de lock ha expirado. Por favor, crea un nuevo lock"
  • "Los campos coin y operation son requeridos"
  • "La operación debe ser BUY o SELL"
  • "El amount debe ser un número válido mayor a 0"
  • "Orden no encontrada en Manteca"

Validaciones

  • "Se requiere un array de monedas"
  • "Moneda X NO está soportada por Manteca"
  • "Par X tiene monedas no soportadas: Y"

Fiat y Transacciones

  • "Todos los campos son requeridos: coin, cbu, amount"
  • "Retiro fiat con ID X no encontrado"
  • "El parámetro page debe ser un número válido mayor a 0"
  • "startDate debe tener el formato YYYY-MM-DD"

KYC y Documentos

  • "Los documentos KYC ya están en Manteca (pendientes o validados)"
  • "Error al procesar documentos KYC"

Bridge​

Customer y Verificación

  • "El usuario ya tiene un customer activo en Bridge con ID: X"
  • "El usuario no tiene un customer activo en Bridge"
  • "El usuario no tiene un customer asociado en Bridge"
  • "Token inválido o expirado"

Cuentas Virtuales

  • "El usuario no tiene un customer activo en Bridge"
  • "No se pudo crear la cuenta virtual"
  • "Moneda no soportada para cuentas virtuales"

KYC y Documentos

  • "Customer y documentos KYC actualizados exitosamente en Bridge"
  • "Error al actualizar documentos KYC en Bridge"

🔧 Validaciones Generales​

Parámetros requeridos

  • "Los campos X y Y son requeridos"
  • "Missing required data"
  • "Se requiere un array de monedas"

Formatos de datos

  • "Invalid email format"
  • "El parámetro page debe ser un número válido mayor a 0"
  • "startDate debe tener el formato YYYY-MM-DD"
  • "El amount debe ser un número válido mayor a 0"

Autenticación

  • "Token is required for this operation"
  • "Invalid token"
  • "Token not provided or invalid"
  • "Unauthorized access"

🚨 Estructura de Respuesta de Error​

Error estándar

{
  "message": "Descripción del error",
  "error": "Tipo de error",
  "statusCode": 400
}

Error con ID de trazabilidad

{
  "message": "Usuario no encontrado",
  "error": "Not Found",
  "statusCode": 404,
  "id": "CF97E6F2"
}

Error de validación

{
  "message": "Los campos coin y operation son requeridos",
  "error": "Bad Request",
  "statusCode": 400,
  "validation": {
    "missing_fields": ["coin", "operation"]
  }
}

🔍 Manejo de Errores por Endpoint​

Manteca​

POST /manteca/create

  • 401: Datos KYC no encontrados
  • 401: Solo usuarios argentinos
  • 409: Usuario ya existe

GET /manteca/user

  • 404: Usuario no encontrado
  • 401: Token inválido

POST /manteca/order/lock

  • 400: Campos faltantes
  • 400: Par no soportado
  • 404: Usuario no activo

POST /manteca/order/execute

  • 400: Lock expirado
  • 400: Campos faltantes
  • 404: Usuario no activo

Bridge​

GET /bridge/generate-tos

  • 409: Customer ya existe
  • 400: Datos incompletos

GET /bridge/customer-status

  • 404: Customer no encontrado
  • 401: Token inválido

POST /bridge/virtual-accounts

  • 404: Customer no activo
  • 400: Moneda no soportada
  • 409: Cuenta ya existe

🛡️ Mejores Prácticas​

Manejo de errores en Frontend

try {
  const response = await fetch('/manteca/order/lock', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(orderData)
  });

  if (!response.ok) {
    const error = await response.json();

    switch (error.statusCode) {
      case 400:
        showValidationError(error.message);
        break;
      case 401:
        redirectToLogin();
        break;
      case 404:
        showNotFoundError();
        break;
      default:
        showGenericError();
    }
    return;
  }

  const data = await response.json();
  // Procesar respuesta exitosa
} catch (networkError) {
  showNetworkError();
}

Logging de errores (Backend)

logger.error('Order lock creation failed', {
  userId: user.id,
  error: error.message,
  errorCode: error.code,
  requestData: orderData,
  timestamp: new Date().toISOString()
});

📊 Códigos de Monitoreo​

Alertas recomendadas

  • 4xx > 10%: Revisar validaciones y UX
  • 5xx > 1%: Posibles problemas de infraestructura
  • Timeouts > 5%: Optimizar performance / dependencia externa

Métricas clave

  • Error Rate: % de requests que fallan
  • MTTR: tiempo promedio de resolución
  • Distribución: por tipo de error y endpoint

📝 Notas Importantes​

Recomendaciones finales

  • Usar IDs de trazabilidad para debugging en logs
  • Mostrar mensajes user-friendly al usuario final
  • Implementar retry sólo para errores 5xx (y con backoff)
  • Configurar alertas por patrones anómalos
  • Mantener esta lista actualizada junto con cambios de API