Gestión de errores

Rueda Lens proporciona mensajes de error coherentes y accionables para ayudarte a diagnosticar problemas rápidamente.

Formato de respuesta de error

Todos los errores siguen una estructura JSON coherente:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  },
  "timestamp": "2026-02-08T12:00:00.000Z"
}

Nota: El campo details solo se incluye cuando hay contexto adicional disponible.

Códigos de estado HTTP

Referencia de códigos de error

MISSING_API_KEY

La cabecera Authorization está ausente o no usa el esquema Bearer.

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "Missing API key"
  }
}

Solución: Incluye tu clave de API como Authorization: Bearer rdlns_sk_... en las cabeceras de la solicitud.

INVALID_API_KEY

La clave de API tiene un formato inválido, no existe, ha sido revocada o ha caducado.

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

Solución: Verifica que tu clave de API sea correcta y esté activa. Si fue revocada o caducó, genera una nueva en tu panel.

INVALID_IMAGE

La imagen proporcionada es inválida. Cubre todos los errores de validación de imagen: campos faltantes, formatos no soportados, base64 corrupto y archivos demasiado grandes.

{
  "error": {
    "code": "INVALID_IMAGE",
    "message": "Invalid request body",
    "details": {
      "field": "tireImage",
      "issue": "Must be a valid base64-encoded image"
    }
  }
}

Problemas comunes:

• Campos obligatorios faltantes: tireImage y carImage
• Codificación base64 inválida
• La imagen supera el límite de 10 MB
• Formato no soportado (solo se aceptan JPEG y PNG)

UNREADABLE_IMAGE

La imagen fue recibida y procesada, pero su contenido no permite una extracción fiable del tamaño del neumático. No es un problema de formato o codificación — la imagen en sí no es apta para el análisis.

{
  "error": {
    "code": "UNREADABLE_IMAGE",
    "message": "Only the tire tread is visible. The sidewall markings where the tire size is printed cannot be read. Please take a photo showing the tire sidewall."
  }
}

Causas comunes:

• La imagen no muestra un neumático (p. ej., objeto aleatorio, paisaje, coche completo sin primer plano del neumático)
• Solo se ve la banda de rodadura (la superficie que toca el suelo) — no se muestra el flanco
• El flanco del neumático es visible pero los marcajes de tamaño están demasiado borrosos, oscuros u ocultos para leerlos
• El ángulo de la imagen no revela el texto del flanco

Solución: Vuelve a tomar la foto asegurándote de que el flanco del neumático sea claramente visible y que los marcajes de tamaño en relieve (p. ej., "225/60R18") sean legibles. Consulta las guías de calidad de imagen.

RATE_LIMIT_EXCEEDED

Límite de solicitudes por minuto superado.

Solución: Espera un momento y reintenta. Este límite previene solicitudes excesivas en un periodo corto.

QUOTA_EXCEEDED

Cuota mensual agotada (solo plan Sandbox, ya que los planes de pago permiten excedentes). Consulta limitación de solicitudes.

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly quota exceeded"
  }
}

Solución: Actualiza tu plan en el panel de facturación, o espera a que tu cuota se reinicie al inicio del siguiente periodo de facturación.

RECOGNITION_FAILED

El análisis con IA no pudo completarse. Suele ocurrir cuando las imágenes no son lo suficientemente claras para identificar el vehículo o leer las especificaciones del neumático.

Causas comunes:

• Imágenes borrosas o desenfocadas
• Iluminación deficiente o sombras intensas
• Texto del neumático oculto o desgastado
• Marcajes de neumáticos inusuales o aftermarket

Solución: Vuelve a tomar las imágenes siguiendo las guías de calidad de imagen. Asegúrate de que el texto del flanco del neumático sea claramente legible y que el vehículo esté bien encuadrado.

SERVICE_UNAVAILABLE

La API no está disponible temporalmente por mantenimiento o alta carga.

Solución: Reintenta con backoff exponencial. Normalmente se resuelve en minutos.

INTERNAL_ERROR

Se ha producido un error inesperado durante el procesamiento.

Solución: Reintenta la solicitud. Si el error persiste, contacta con soporte en support@ruedalens.com incluyendo el requestId de la respuesta.

Buenas prácticas

Gestión completa de errores

async function analyzeVehicle(tireImage, carImage) {
  const response = await fetch('https://api.ruedalens.com/v1/analyze', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.RUEDA_LENS_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ tireImage, carImage }),
  });

  const data = await response.json();

  if (!data.success) {
    switch (data.error.code) {
      case 'MISSING_API_KEY':
        throw new Error('API key is missing. Add Authorization header.');
      case 'INVALID_API_KEY':
        throw new Error('Invalid API key. Check your credentials.');
      case 'INVALID_IMAGE':
        throw new Error(`Invalid image: ${data.error.message}`);
      case 'UNREADABLE_IMAGE':
        throw new Error(`Image not suitable: ${data.error.message}`);
      case 'QUOTA_EXCEEDED':
        throw new Error('Monthly quota exceeded. Upgrade your plan or wait for reset.');
      case 'RATE_LIMIT_EXCEEDED':
        throw new Error('Rate limit exceeded. Wait a moment and retry.');
      case 'RECOGNITION_FAILED':
        throw new Error('Could not analyze images. Ensure tire text and vehicle are clearly visible.');
      default:
        throw new Error(data.error.message);
    }
  }

  return data.data;
}

Backoff exponencial para reintentos

async function withRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;

      const delay = Math.pow(2, attempt) * 1000;
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}

Obtener ayuda

Si encuentras errores persistentes:

1. Comprueba el endpoint de salud de la API: GET /v1/health
2. Revisa tus logs de solicitudes en el panel
3. Contacta con soporte en support@ruedalens.com con el código de error, el ID de la solicitud y la marca temporal