Errors · Quotes API

Errors#

This is the error format of Just's REST APIs, the Quotes API among them. Every error a REST API returns is an RFC 9457 problem, with Content-Type: application/problem+json. Branch on status and the last segment of type, and log the Request-Id header, which the body repeats as requestId. The one exception is the gateway's 401.

typestring, URI

https://docs.just.insure/quotes/errors# followed by a stable name from the table below.

titlestring

Short summary, for example "Invalid request".

statusinteger

The HTTP status.

detailstringOptional

For developers. Never contains Just's internal error text.

requestIdstring

The call's id, the same value as the Request-Id header, for example req_01M504WZ3F1HEAD8X4A1JH69RE. Send it to Just to have an error looked into.

errorsarray of objectsOptional

On a 400 about the body's content: every problem found, so you can fix them all at once. Each has path (for example policyholder.dateOfBirth; "" is the whole body), code (see field problem codes) and message (for people; can change).

Status	`type`	Meaning	Retry?
400	`invalid-request`	The body has problems, all in `errors`. Without `errors`: the body isn't valid JSON, or is empty.	No, fix the request
401	gateway body	Missing or unknown `x-api-key`.	No
403	`forbidden`	The key isn't enabled for this API.	No
413	`invalid-request`	Body over 64 KiB.	No
415	`invalid-request`	`Content-Type` isn't `application/json`.	No
500	`internal-error`	Something went wrong at Just.	Yes, with backoff
502	`dependency-failure`	A service Just depends on failed.	Yes, with backoff
504	`dependency-timeout`	Pricing didn't finish in time.	Yes, with backoff

A 5xx fails the whole request, even when one product was already priced or declined: a partial answer would hide the fault. Don't show a price from an earlier response for this shopper unless it's still before its expiresAt.

Handle the response

if (res.status === 200) {
  const { quotes, declines } = await res.json();
  return showQuotes(quotes, declines);
}

const problem = await res.json().catch(() => ({}));
const kind = (problem.type ?? "").split("/").pop();
log.warn("just quote failed", {
  status: res.status, kind, requestId: res.headers.get("Request-Id"),
  problems: problem.errors?.map(e => `${e.path} ${e.code}`)
});

if (res.status >= 500) return retryWithBackoff();
return hideJust(); // 4xx: fix the request or the key

The request behind the 400 example

{
  "package": "BASIC_FULL_COVER",
  "policyholder": {
    "firstName": "Alex",
    "lastName": "Rivera",
    "dateOfBirth": "04/12/1991",
    "gender": "MALE",
    "email": "alex.rivera@example.com",
    "phone": "602-555-0143",
    "address": { "line1": "302 W Almeria Rd", "city": "Phoenix", "state": "AZ", "zipCode": "85003" },
    "creditScoreBand": "GOOD"
  },
  "vehicles": [
    { "partialVin": "19XFA1F5*A", "vin": "1GC0K9CG0BF213909", "estimatedMonthlyMileage": "800" }
  ]
}

Field problem codes#

The code of each entry in a 400's errors. Codes are stable; branch on them. Messages are for people and can change.

`code`	Meaning	Example `path`
`MISSING_FIELD`	A required field is missing.	`policyholder.email`
`INVALID_TYPE`	Wrong JSON type, for example a string for a number, or `null` where not allowed.	`vehicles[0].estimatedMonthlyMileage`
`INVALID_ENUM_VALUE`	Not one of the accepted values, for example an `acdCode` Just doesn't rate in the policyholder's state. The message lists them, or for `acdCode` names the state.	`policyholder.gender`
`INVALID_DATE`	Not a real ISO 8601 date in `YYYY-MM-DD` form.	`policyholder.dateOfBirth`
`INVALID_EMAIL`	Not an email address.	`policyholder.email`
`INVALID_FORMAT`	Wrong format: VIN, partial VIN, state, ZIP, phone.	`policyholder.address.zipCode`
`INVALID_LENGTH`	Empty, or too long. Also an `Idempotency-Key` header over 255 characters, at path `Idempotency-Key`.	`policyholder.firstName`
`OUT_OF_RANGE`	A number below its minimum or above its maximum.	`vehicles[0].estimatedMonthlyMileage`
`TOO_FEW_ITEMS`	An array with too few items, for example `vehicles: []`.	`vehicles`
`TOO_MANY_ITEMS`	An array over its limit: 9 additional drivers, 10 vehicles, 50 history events.	`policyholder.history.claims`
`DUPLICATE_ITEMS`	A repeated value.	`products`
`INVALID_VALUE`	Well-formed, but Just's rating rejected the value. The message, from Just, says why, for example `State does not match zip code. Expected AZ`.	`policyholder.address.state`
`VEHICLE_IDENTIFIER_REQUIRED`	The vehicle has neither `vin` nor `partialVin`.	`vehicles[0]`
`VEHICLE_IDENTIFIER_AMBIGUOUS`	The vehicle has both `vin` and `partialVin`.	`vehicles[0]`
`VIOLATION_IDENTIFIER_REQUIRED`	The violation has neither `acdCode` nor `severity`.	`policyholder.history.violations[0]`
`VIOLATION_IDENTIFIER_AMBIGUOUS`	The violation has both `acdCode` and `severity`.	`policyholder.history.violations[0]`
`CREDIT_SCORE_REQUIRED`	Neither `creditScore` nor `creditScoreBand` was sent.	`policyholder`
`CREDIT_SCORE_AMBIGUOUS`	Both `creditScore` and `creditScoreBand` were sent.	`policyholder`
`POLICY_START_DATE_IN_PAST`	Before today in the policyholder's time zone.	`policyStartDate`
`POLICY_START_DATE_TOO_FAR_AHEAD`	More than 60 days after today in the policyholder's time zone.	`policyStartDate`

Questions go to your Just partnership contact. Include the Request-Id response header of the call, and the quote's id for a question about a quote, so Just can find it.