Error Handling

All API errors follow a consistent JSON format.

Error Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of the error.",
    "status": 400
  }
}

Error Codes

Code	HTTP Status	Description
INVALID_API_KEY	401	API key is missing, invalid, or deactivated
RATE_LIMIT_EXCEEDED	429	Too many requests — wait and retry
INVALID_REQUEST	400	Request body is malformed or missing required fields
DEALER_NOT_FOUND	404	The specified dealership does not exist or is not active
VEHICLE_NOT_FOUND	404	The specified vehicle was not found in the dealer's inventory
INSUFFICIENT_CREDITS	402	The dealer does not have enough credits to fulfil the quote
INTERNAL_ERROR	500	An unexpected server error occurred

Validation Errors

For INVALID_REQUEST errors, the message field contains details about which fields failed validation:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "clientName is required; clientEmail must be a valid email address",
    "status": 400
  }
}

Retry Strategy

• 401/403: Do not retry — check your API key
• 429: Retry after waiting (respect the rate limit window)
• 400/404: Do not retry — fix the request
• 500: Retry with exponential backoff (1s, 5s, 25s)