Error Handling

Rueda Lens provides consistent, actionable error messages to help you diagnose issues quickly.

Error Response Format

All errors follow a consistent JSON structure:

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

Note: The details field is only included when additional context is available.

HTTP Status Codes

Error Codes Reference

MISSING_API_KEY

The Authorization header is missing or doesn't use the Bearer scheme.

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

Fix: Include your API key as Authorization: Bearer rdlns_sk_... in the request headers.

INVALID_API_KEY

The API key has an invalid format, doesn't exist, has been revoked, or has expired.

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

Fix: Verify your API key is correct and active. If it was revoked or expired, generate a new one in your dashboard.

INVALID_IMAGE

The provided image is invalid. This covers all image-related validation errors including missing fields, unsupported formats, corrupted base64, and oversized files.

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

Common issues:

• Missing required fields: tireImage and carImage
• Invalid base64 encoding
• Image exceeds 10 MB size limit
• Unsupported format (only JPEG and PNG are accepted)

RATE_LIMIT_EXCEEDED

Per-minute burst rate limit exceeded.

Fix: Wait a moment and retry. This limit prevents excessive requests in a short period.

QUOTA_EXCEEDED

Monthly quota exhausted (Sandbox plan only, as paid plans support overage billing). See Rate Limiting.

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

Fix: Upgrade your plan in the billing dashboard, or wait for your quota to reset at the start of your next billing period.

RECOGNITION_FAILED

AI analysis could not complete. This typically occurs when the images are too unclear to identify the vehicle or read the tire specifications.

Common causes:

• Blurry or out-of-focus images
• Poor lighting or heavy shadows
• Tire text obscured or worn away
• Unusual or aftermarket tire markings

Fix: Retake the images following the image quality guidelines. Ensure tire sidewall text is clearly legible and the vehicle is well-framed.

SERVICE_UNAVAILABLE

The API is temporarily unavailable due to maintenance or high load.

Fix: Retry with exponential backoff. This is typically resolved within minutes.

INTERNAL_ERROR

An unexpected error occurred during processing.

Fix: Retry the request. If the error persists, contact support at support@ruedalens.com with the requestId from the response.

Best Practices

Comprehensive Error Handling

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 '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;
}

Exponential Backoff for Retries

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));
    }
  }
}

Getting Help

If you encounter persistent errors:

1. Check the API health endpoint: GET /v1/health
2. Review your request logs in the dashboard
3. Contact support at support@ruedalens.com with the error code, request ID, and timestamp