Errors and Rate Limits

The error envelope

Partner API responses are wrapped, except the registration endpoints (/api/v2/Partners/Register*): their success bodies are plain objects, and Register and Verify answer 400 as one plain-text sentence. See Registration and authentication endpoints. In a wrapped response, 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, connection failures, a plan search 400 with SystemError, and the two registration server-problem sentences (An error occurred during registration. Please try again. and An error occurred during verification. Please try again.) 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.

Registration and authentication endpoints

POST /api/v2/Partners/Register and POST /api/v2/Partners/Register/Verify do not use the error envelope above. They answer 400 with one plain sentence and Content-Type: text/plain. There is no errorResponse, so do not parse the body as JSON. If there are several problems, the sentences are joined with a space. The Partners/Authentication endpoints answer a missing or invalid body the same way.

A 415 Unsupported Media Type means the Content-Type is not application/json.

POST /Register/Rotate and DELETE /Register answer 400, and GET /Register/Usage answers 404, with a JSON body whose errors[0].errorMessage is No active registration found. (full shape: {"errors":[{"errorMessage":"No active registration found.","errorField":null,"errorCode":null,"errorNumber":null}]}) when the key's partner has no active self-service registration, for example after a Delete that ran at the same moment. This body has no response/errorResponse wrapper. The same status with an errorMessage that starts with An error occurred is a server problem, not a missing registration: retry it later. A 401 means the key is missing, invalid, rotated out or deleted. POST /Register/Rotate and DELETE /Register also answer 401 when the key is valid but is not the registration's current key, for example a key that a parallel Rotate already replaced: nothing is changed. The 401 body is empty or an application/problem+json object with title Unauthorized, never the errors object.

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.

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.

Coverage limits

These are hard limits. Within them, a vehicle no provider wants to cover comes back as an empty results array, not an error. See Restrictions and limitations.

Tell the customer what happened rather than retrying. These do not change with a different request.

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.

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;

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.
• Search again rather than reusing a result older than 30 days.
• Retry only on 5xx, connection errors, 429 after Retry-After, a plan search SystemError, and the two registration server-problem sentences (An error occurred during registration… and An error occurred during verification…).
• 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.