Error Codes Reference

This document provides a comprehensive list of error codes returned by the Chaiz Partner API, based on actual API response examples.

Response Format

All error responses follow a consistent structure with errorMessage, errorField, errorCode, errorNumber, and optional suggestions fields.

{
  "response": null,
  "errorResponse": {
    "errors": [
      {
        "errorMessage": "Can't parse vin: invalidvin",
        "errorField": "VIN",
        "errorCode": "CantParseVIN",
        "errorNumber": 4005,
        "suggestions": [
          {
            "action": "CheckInput",
            "message": "Verify the VIN is exactly 17 alphanumeric characters (no I, O, or Q)."
          },
          {
            "action": "RetryWithAlternative",
            "message": "Search by make, model, and year instead.",
            "endpoint": "/api/v2/Partners/PlansSearch/MakeModelYear"
          }
        ]
      }
    ]
  }
}

Response Fields

Field	Type	Description
`errorMessage`	string	Human-readable error description
`errorField`	string	The field that caused the error (may be null)
`errorCode`	string	Machine-readable error code identifier
`errorNumber`	integer	Numeric error code for categorization
`suggestions`	array	Actionable suggestions for resolving the error (may be absent)

Suggestion Fields

Each suggestion object contains:

Field	Type	Description
`action`	string	Type of suggestion: `RetryWithAlternative`, `CheckInput`, `ContactSupport`, `UseDifferentEndpoint`
`message`	string	Human-readable suggestion that can be presented directly to users
`endpoint`	string	Alternative API endpoint to try (only present for `RetryWithAlternative` and `UseDifferentEndpoint`)

The suggestions field is designed for AI agents and automated integrations. Each suggestion provides a clear action type and a human-readable message that can be presented directly to end users without additional interpretation.

Error Code Categories

Range	Category	Description
4xxx	Validation Errors	Input field and data validation
20xxx	Partner Errors	Partner-specific validation and business logic

Error Codes by Category

Number	Code	Field	Message	Resolution
4001	ZipAndStateAreEmpty	ZipAndState	Zip and State can't both be empty	Provide either zip code or state
4002	CarDetailsAreEmpty	CarDetails	Car details: make, model, year, license plate and VIN can't be empty	Provide at least one vehicle identifier
4005	CantParseVIN	VIN	Can't parse vin: `{vin}`	Verify VIN is valid 17-character format
4006	CantParseLicensePlate	LicensePlate	Can't parse licensePlate: `{plate}`	Verify license plate format
4009	MileageIsLessThanZero	Mileage	Mileage can't be less than 0	Provide a positive mileage value
4013	StateShortNameIsInvalid	StateShortName	State short name is invalid: `{state}`	Use valid 2-letter US state code
4014	MakeIsInvalid	Make	Can't find make Id for make: `{make}`	Verify vehicle make spelling
4015	ModelIsInvalid	Model	Can't find model Id for make: `{make}` and model: `{model}`	Verify model exists for the specified make
4017	DurationFilterCantbeEmpty	DurationFilter	Duration filter can't be empty	Specify a duration filter value
4019	MileageIsRequired	Mileage	Mileage can't be 0	Provide a non-zero mileage value

Number	Code	Field	Message	Resolution
20004	DurationFilterRestictedValues	DurationFilter	Duration filter can be only 3 months or 36 months	Use allowed duration values (3 or 36 months)
20005	DurationFilterRestrictedRange	DurationFilter	Duration filter 'from' should be equal to 'to'	Ensure duration range from and to values match
20006	VinHasNotBeenRegistered	(null)	Vin: `{vin}` with mileage: `{mileage}` hasn't been registered yet. Please register your VIN with mileage first.	Register the VIN before searching for plans

When creating orders, UserDetails validation may return errors with null errorCode and errorNumber:

{
  "response": null,
  "errorResponse": {
    "errors": [
      {
        "errorMessage": "The City field is required.",
        "errorField": "UserDetails.City",
        "errorCode": null,
        "errorNumber": null
      }
    ]
  }
}

Required UserDetails Fields

Field	Error Message
UserDetails.City	The City field is required.
UserDetails.Email	The Email field is required.
UserDetails.State	The State field is required.
UserDetails.Address	The Address field is required.
UserDetails.LastName	The LastName field is required.
UserDetails.FirstName	The FirstName field is required.
UserDetails.PhoneNumber	The PhoneNumber field is required.
UserDetails.Zip	The Zip field is required.

Simple Format Errors

Some endpoints return errors in a simplified format without errorNumber:

{
  "response": null,
  "errorResponse": {
    "errors": [
      {
        "errorMessage": "VIN is required.",
        "errorField": null,
        "errorCode": "EmptyValue",
        "errorNumber": null
      }
    ]
  }
}

Code	Message	Resolution
EmptyValue	VIN is required.	Include VIN in the request

HTTP Status Codes

Status	Meaning	When Returned
200	OK	Request successful with results
201	Created	Resource created (e.g., search completed)
202	Accepted	Request accepted, processing in progress
400	Bad Request	Validation failed - check errorResponse
401	Unauthorized	Invalid or missing authentication token
403	Forbidden	Token lacks required permissions
410	Gone	Resource no longer available
500	Internal Server Error	Server-side error occurred

Error Handling Best Practices

1. Check for Errors and Use Suggestions

const data = await response.json();

if (data.errorResponse?.errors?.length > 0) {
  const error = data.errorResponse.errors[0];
  console.error(`Error ${error.errorCode} (${error.errorNumber}): ${error.errorMessage}`);

  // Use suggestions for actionable guidance
  if (error.suggestions?.length > 0) {
    for (const suggestion of error.suggestions) {
      console.log(`[${suggestion.action}] ${suggestion.message}`);
      if (suggestion.endpoint) {
        console.log(`  Try: ${suggestion.endpoint}`);
      }
    }
  }
  return;
}

const plans = data.response;

2. Validate Input Before Requests

function validateSearchRequest(request) {
  const errors = [];

  if (!request.vin || request.vin.length !== 17) {
    errors.push({ code: 'CantParseVIN', message: 'VIN must be 17 characters' });
  }

  if (!request.mileage || request.mileage <= 0) {
    errors.push({ code: 'MileageIsLessThanZero', message: 'Invalid mileage' });
  }

  if (!request.state && !request.zip) {
    errors.push({ code: 'ZipAndStateAreEmpty', message: 'Provide state or zip' });
  }

  return errors;
}

Need Help?

If you encounter an error code not listed here or need assistance:

Email: dev-support@chaiz.com
Include the full error response and request details (with sensitive data removed)

Leads