Error Codes Reference

This document catalogs all possible error types that clients may encounter when using the Auto.dev API Gateway.

Error Response Structure

All API errors follow a consistent JSON structure:

interface ApiError {
  status: number // HTTP status code (400, 401, 404, 500, etc.)
  error: string // Human-readable error description
  code: string // Programmatic error identifier
  path: string // API endpoint path that generated the error
  requestId: string // Unique identifier for debugging and support
  suggestion?: string // Helpful guidance for resolution (optional)
  message?: string // Alternative error description (legacy/some endpoints)
  upgradeLink?: string // Link to upgrade subscription (payment errors)
  errorType?: string // Legacy error type classification
}

Field Usage Across APIs:

status - HTTP status code (universal)
error - Primary error message (universal)
code - Error code identifier (universal)
path - Request path (universal)
requestId - Debug identifier (universal)
suggestion - Resolution guidance (taxes API)
message - Alternative to error (auth, legacy)
upgradeLink - Payment upgrade link (402 errors)
errorType - Legacy VIN validation errors

HTTP Status Codes

400 - Bad Request

Invalid Location

Code: INVALID_LOCATION

{
  "status": 400,
  "error": "Invalid ZIP code format. ZIP code must be 5 digits (e.g., 90210) or 5+4 format (e.g., 90210-1234)",
  "code": "INVALID_LOCATION",
  "path": "/taxes/invalidzip",
  "requestId": "a1b2c3d4e5f6g7h8",
  "suggestion": "Please provide a valid 5-digit ZIP code or ZIP+4 format"
}

Invalid VIN Format

Code: INVALID_VIN_FORMAT

{
  "status": 400,
  "error": "VIN must be exactly 17 characters containing only letters and numbers (excluding I, O, Q)",
  "code": "INVALID_VIN_FORMAT",
  "path": "/vin/123Invalid",
  "requestId": "a1b2c3d4e5f6g7h8"
}

Invalid License Plate Format

Code: INVALID_PLATE_FORMAT

{
  "status": 400,
  "error": "License plate must be 2-8 alphanumeric characters",
  "code": "INVALID_PLATE_FORMAT",
  "path": "/plate/A?state=CA",
  "requestId": "b2c3d4e5f6g7h8i9"
}

Invalid State Code

Code: INVALID_STATE_CODE

{
  "status": 400,
  "error": "State must be a valid 2-letter US state code (e.g., CA, NY, TX)",
  "code": "INVALID_STATE_CODE",
  "path": "/plate/ABC123?state=XX",
  "requestId": "c3d4e5f6g7h8i9j0"
}

Invalid Parameter

Code: INVALID_PARAMETER

{
  "status": 400,
  "error": "Invalid parameter provided: make. This parameter does not exist in this endpoint.",
  "code": "INVALID_PARAMETER",
  "path": "/listings",
  "requestId": "966e8386bb38f095"
}

Invalid Request

Code: INVALID_REQUEST

{
  "status": 400,
  "error": "Invalid request format or missing required parameters",
  "code": "INVALID_REQUEST",
  "path": "/api/endpoint",
  "requestId": "d4e5f6g7h8i9j0k1"
}

401 - Unauthorized

Authentication Required

Code: UNAUTHORIZED

{
  "status": 401,
  "message": "Sign up for an API Key at https://api.vin/login",
  "code": "UNAUTHORIZED",
  "path": "/vin/1HGCM82633A123456",
  "requestId": "e5f6g7h8i9j0k1l2"
}

402 - Payment Required

Payment Required

Code: PAYMENT_REQUIRED

{
  "status": 402,
  "error": "Payment Required",
  "code": "PAYMENT_REQUIRED",
  "path": "/advanced-endpoint",
  "requestId": "f6g7h8i9j0k1l2m3",
  "upgradeLink": "https://driv.ly/upgrade"
}

403 - Forbidden

Forbidden Access

Code: FORBIDDEN

{
  "status": 403,
  "error": "Forbidden",
  "code": "FORBIDDEN",
  "path": "/restricted-endpoint",
  "requestId": "g7h8i9j0k1l2m3n4"
}

404 - Not Found

VIN Not Found

Code: VIN_NOT_FOUND

{
  "status": 404,
  "error": "No vehicle data found for the provided VIN",
  "code": "VIN_NOT_FOUND",
  "path": "/vin/WP0AF2A99KS165242",
  "requestId": "b2c3d4e5f6g7h8i9"
}

License Plate Not Found

Code: PLATE_NOT_FOUND

{
  "status": 404,
  "error": "No vehicle found for the provided license plate",
  "code": "PLATE_NOT_FOUND",
  "path": "/plate/NOTFOUND?state=CA",
  "requestId": "h8i9j0k1l2m3n4o5"
}

No Data Found

Code: NO_DATA_FOUND

{
  "status": 404,
  "error": "License plate found but no vehicle data available",
  "code": "NO_DATA_FOUND",
  "path": "/plate/ABC123?state=CA",
  "requestId": "i9j0k1l2m3n4o5p6"
}

Resource Not Found

Code: RESOURCE_NOT_FOUND

{
  "status": 404,
  "error": "Resource \"WP0AF2A99KS165242\" not found",
  "code": "RESOURCE_NOT_FOUND",
  "path": "/listings/WP0AF2A99KS165242",
  "requestId": "966716ac29ed8147"
}

422 - Unprocessable Entity

VIN Decode Failed

Code: VIN_DECODE_FAILED

{
  "status": 422,
  "error": "Unable to decode VIN: 1HGBH41JXMN109186",
  "code": "VIN_DECODE_FAILED",
  "path": "/vin/1HGBH41JXMN109186",
  "requestId": "j0k1l2m3n4o5p6q7"
}

Payment Calculation Error

Code: PAYMENT_CALCULATION_ERROR

{
  "status": 422,
  "error": "Cannot calculate payments with provided data",
  "code": "PAYMENT_CALCULATION_ERROR",
  "path": "/payments/1GYKPDRSXSZ102995",
  "requestId": "k1l2m3n4o5p6q7r8"
}

429 - Too Many Requests

Rate Limit Exceeded

Code: RATE_LIMIT_EXCEEDED

{
  "status": 429,
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "path": "/vin/1HGCM82633A123456",
  "requestId": "l2m3n4o5p6q7r8s9"
}

500 - Internal Server Error

Internal Server Error

Code: INTERNAL_SERVER_ERROR

{
  "status": 500,
  "error": "500 - Internal Server Error",
  "code": "INTERNAL_SERVER_ERROR",
  "path": "/api/endpoint",
  "requestId": "m3n4o5p6q7r8s9t0",
  "message": "An unexpected error occurred, please try again later."
}

503 - Service Unavailable

Source Error

Code: SOURCE_ERROR

{
  "status": 503,
  "error": "External service temporarily unavailable",
  "code": "SOURCE_ERROR",
  "path": "/payments/1GYKPDRSXSZ102995",
  "requestId": "c3d4e5f6g7h8i9j0"
}

Legacy Error Formats

VIN Validation (Legacy Format)

Some endpoints may still return legacy error formats:

{
  "status": 400,
  "error": "VIN validation failed",
  "code": "VIN_VALIDATION_ERROR",
  "path": "/legacy/vin/invalid",
  "requestId": "n4o5p6q7r8s9t0u1",
  "errorType": "VALIDATION_ERROR"
}

Error Handling Best Practices

Client Implementation

Always check the status code first
Use the code field for programmatic error handling
Display the error message to users (human-readable)
Log the requestId for debugging and support
Implement retry logic for 5xx errors with exponential backoff

Getting Help

When contacting support, please include:

Request ID from the error response
Full error response JSON
Request details (endpoint, parameters, headers)
Expected behavior vs. actual behavior

Error Codes Reference

On this page