CheapVHR API Documentation

Error Responses

Understanding error codes and responses from the CheapVHR API

Error Response Format

All error responses follow a consistent JSON structure

{
  "error": "Error Type",
  "message": "Detailed error description",
  "code": 400
}

400

Bad Request

The request was invalid or cannot be served

Invalid VIN format

{
  "error": "Invalid VIN format",
  "message": "VIN must be 17 characters long",
  "code": 400
}

Missing required parameters

{
  "error": "Missing required parameter",
  "message": "VIN parameter is required",
  "code": 400
}

401

Unauthorized

Authentication failed or API key is invalid

Missing API key

{
  "error": "Unauthorized",
  "message": "API key is required",
  "code": 401
}

Invalid API key

{
  "error": "Unauthorized",
  "message": "Invalid API key",
  "code": 401
}

404

Not Found

The requested resource was not found

Report not found

{
  "error": "Not Found",
  "message": "Report with ID 12345 not found",
  "code": 404
}

Invalid endpoint

{
  "error": "Not Found",
  "message": "Endpoint not found",
  "code": 404
}

429

Too Many Requests

Rate limit exceeded

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Try again in 60 seconds",
  "code": 429,
  "retry_after": 60
}

500

Internal Server Error

An unexpected error occurred on the server

Server error

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred",
  "code": 500
}

Handling Errors

Best practices for error handling in your application

JavaScript Example

try {
  const response = await fetch('https://api.cheapvhr.com/v1/user/info', {
    headers: {
      'x-api-key': 'your-api-key'
    }
  });
  
  if (!response.ok) {
    const error = await response.json();
    console.error(`Error ${error.code}: ${error.message}`);
    return;
  }
  
  const data = await response.json();
  // Handle success
} catch (error) {
  console.error('Network error:', error);
}

Error Handling Tips

Always check the HTTP status code before processing the response
Parse error responses to get detailed error information
Implement retry logic for 5xx server errors
Respect rate limits and implement exponential backoff for 429 errors
Log errors for debugging and monitoring purposes