Errors and Rate Limits

The error envelope

Every response is wrapped. response carries the payload, errorResponse carries the problems, and exactly one of them is populated.

{
  "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"
          }
        ]
      }
    ]
  }
}

The field is errorResponse, and the payload field is response. Neither is called data.

Suggestions

Where present, suggestions tells you what to do next without you having to encode the rules yourself.

This is especially useful for AI agents and automated integrations: a RetryWithAlternative with an endpoint is a machine-followable instruction.

HTTP status codes

Only 5xx and connection failures are safe to retry blindly. Never retry a slow plan search: it has not failed, and a retry starts a second independent search that quotes the vehicle twice.

Validation errors (4xxx)

4014 and 4015 are the most common errors in new integrations, and almost always mean you are sending customer-typed text straight through. Resolve it first.

Account and plan errors (20xxx)

These are configuration talking to you, not bugs in your request. If a restriction does not match what you expected to sell, contact dev-support@chaiz.com rather than working around it.

Order errors

Customer detail validation returns per-field errors with a null errorCode and errorNumber:

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

errorField is the path, so UserDetails.City points straight at the offending input. Required fields are firstName, lastName, email, address, city, state, and zip; the format rules are on Full API Checkout. Validate in your own form first so a customer who has already entered a card is not the one to find out.

Some endpoints use a shorter form with no errorNumber, for example errorCode: "EmptyValue" with errorMessage: "VIN is required.". Handle a missing errorNumber rather than assuming it is present.

Rate limits

Limits are per partner account, not per IP, and they apply as two simultaneous windows: hourly and daily. Both must have room for a request to pass.

GET /api/v2/Partners/Register/Usage returns your current tier and limits. Ask dev-support@chaiz.com about a higher tier before launch rather than after you start hitting 429s.

Exceeding a limit returns 429 with a Retry-After header in seconds.

Retry-After appears on 429 only. A 202 from async search does not carry one; poll on your own 1 to 2 second interval instead.

Handling errors well

Read errorResponse before anything else, and use suggestions when they are there:

const body = await response.json();
const errors = body.errorResponse?.errors;

if (errors?.length) {
  for (const e of errors) {
    console.error(`${e.errorCode ?? 'validation'} (${e.errorNumber ?? '-'}): ${e.errorMessage}`);

    for (const s of e.suggestions ?? []) {
      // s.message is written to be shown to the customer as-is
      console.log(`[${s.action}] ${s.message}${s.endpoint ? ` -> ${s.endpoint}` : ''}`);
    }
  }
  return;
}

const plans = body.response.results;

Order creation needs the status code checked explicitly, because its failure path is also a 2xx:

// order creation returns an ARRAY of wrappers, one per plan ordered
const body = await response.json();

if (response.status !== 201) {
  const errors = body.flatMap(w => w.errorResponse?.errors ?? []);
  return { ok: false, errors };
}

const orderIds = body.map(w => w.response); // each is a single order id string

A short checklist that removes most avoidable failures:

• Resolve make and model through Vehicle Lookup instead of passing customer text through.
• Require state and mileage in your own form, and validate the VIN is 17 characters.
• Re-search rather than reusing a searchResultPlanId older than 30 days.
• Retry only on 5xx, connection errors, and 429 after Retry-After.
• Log errorCode and errorNumber, not just the message. The message wording can change; the codes are stable.

Still stuck?

Email dev-support@chaiz.com with the full error response, the request body, and roughly when the call happened. Remove card numbers and personal data first.