{
  "success": false,
  "data": null,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": {
      "field": "Additional error context"
    }
  }
}

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The API key provided is invalid"
  }
}

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required for authentication"
  }
}

{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked"
  }
}

{
  "error": {
    "code": "INVALID_FILE_FORMAT",
    "message": "File format not supported. Allowed formats: PDF, JPG, PNG",
    "details": {
      "allowed_formats": ["pdf", "jpg", "jpeg", "png", "webp"],
      "received_format": "doc"
    }
  }
}

{
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File size exceeds the maximum limit of 10MB",
    "details": {
      "max_size_bytes": 10485760,
      "received_size_bytes": 15728640
    }
  }
}

{
  "error": {
    "code": "CORRUPTED_FILE",
    "message": "The uploaded file appears to be corrupted"
  }
}

{
  "error": {
    "code": "MISSING_FILE",
    "message": "A file must be provided for processing"
  }
}

{
  "error": {
    "code": "UNREADABLE_TEXT",
    "message": "The text in the image is too blurry to read accurately"
  }
}

{
  "error": {
    "code": "NO_INVOICE_DETECTED",
    "message": "No invoice content could be detected in this document"
  }
}

{
  "error": {
    "code": "PROCESSING_TIMEOUT",
    "message": "Document processing timed out"
  }
}

{
  "error": {
    "code": "UNSUPPORTED_LANGUAGE",
    "message": "Document language is not currently supported",
    "details": {
      "detected_language": "zh",
      "supported_languages": ["en", "es", "fr", "de", "it"]
    }
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please slow down your requests",
    "details": {
      "limit": 100,
      "window": "hour",
      "retry_after": 3600
    }
  }
}

{
  "error": {
    "code": "INVALID_WEBHOOK_URL",
    "message": "Webhook URL must be a valid HTTPS URL",
    "details": {
      "provided_url": "http://example.com/webhook"
    }
  }
}

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid parameter value",
    "details": {
      "parameter": "extract_line_items",
      "expected": "boolean",
      "received": "string"
    }
  }
}

{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An internal error occurred. Please try again later"
  }
}

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable for maintenance"
  }
}

async function extractInvoiceWithRetry(file, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await smartbills.invoices.extract({ file });
    } catch (error) {
      const shouldRetry = [500, 502, 503, 504].includes(error.status) ||
                         error.code === 'PROCESSING_TIMEOUT';
      
      if (shouldRetry && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      
      throw error;
    }
  }
}

try {
  const result = await smartbills.invoices.extract({ file });
} catch (error) {
  switch (error.code) {
    case 'INVALID_FILE_FORMAT':
      // Show user-friendly message about file format
      showError('Please upload a PDF, JPG, or PNG file');
      break;
      
    case 'FILE_TOO_LARGE':
      // Suggest file compression
      showError('File is too large. Please compress and try again');
      break;
      
    case 'RATE_LIMIT_EXCEEDED':
      // Implement backoff and retry
      const retryAfter = error.details.retry_after;
      setTimeout(() => retryUpload(), retryAfter * 1000);
      break;
      
    case 'UNREADABLE_TEXT':
      // Suggest better image quality
      showError('Image quality is too low. Please use a clearer scan');
      break;
      
    default:
      // Generic error handling
      showError('Something went wrong. Please try again');
  }
}

const errorMetrics = {
  total: 0,
  byCode: {},
  byStatus: {}
};

function trackError(error) {
  errorMetrics.total++;
  errorMetrics.byCode[error.code] = (errorMetrics.byCode[error.code] || 0) + 1;
  errorMetrics.byStatus[error.status] = (errorMetrics.byStatus[error.status] || 0) + 1;
}