Response Handling

The Pricing Insights API uses a consistent response envelope for both successful and failed requests.

Response Envelope

Every response includes a meta object with a status field and a data object with the payload.

{
  "meta": { "status": "success" },
  "data": { }
}

• meta.status is "success" for 2xx responses and "fail" for error responses.
• data holds the recommendation on success, or the error details on failure.

Success Response

{
  "meta": { "status": "success" },
  "data": {
    "price": 1272,
    "price_per_mile": 0.88,
    "distance_miles": 1450,
    "confidence": 69,
    "volume": 42
  }
}

The v2 endpoint adds price_range_lower, price_range_upper, and recent_moves. See the Quickstart for a full v2 example.

Error Responses

Error responses set meta.status to "fail". Some errors include a type field identifying the specific condition.

Status	type	Meaning
400	SAME_ZIP_CODES	Pickup and delivery ZIP codes are identical.
400	NO_ROUTE_AVAILABLE	No drivable route exists between the locations.
401	—	API key is missing or invalid.
403	—	Usage quota exceeded.
422	—	Request body failed validation.
429	—	Rate limit exceeded (50 requests / 10 seconds).

Same ZIP Codes (400)

{
  "meta": { "status": "fail" },
  "data": {
    "type": "SAME_ZIP_CODES",
    "message": "Recommended Price isn't available when Pickup and Delivery ZIP codes are the same.",
    "details": {
      "reason": "Pickup and Delivery ZIP codes must be different to generate a Recommended Price.",
      "next_steps": [
        "Enter different ZIP codes for Pickup and Delivery locations.",
        "If this is a local move, pricing may need to be handled manually or through a custom rate."
      ]
    }
  }
}

No Route Available (400)

{
  "meta": { "status": "fail" },
  "data": {
    "type": "NO_ROUTE_AVAILABLE",
    "message": "Pickup or delivery location is not accessible by road.",
    "details": {
      "reason": "The routing engine could not find a drivable path between the provided locations. One of the ZIP codes may be in a region without road access or outside supported routing coverage.",
      "next_steps": [
        "Some locations may require special handling, such as ocean or air transport.",
        "Consider splitting the route into separate legs—for example, to and from a nearby mainland or serviceable area.",
        "If this is expected behavior, consider handling routing manually or using a different provider for this segment."
      ]
    }
  }
}

Unauthorized (401)

{
  "meta": { "status": "fail" },
  "data": {
    "message": "Token provided is invalid",
    "details": []
  }
}

Forbidden — Quota Exceeded (403)

{
  "meta": { "status": "fail" },
  "data": { "message": "The request cannot be completed because you have exceeded your quota" }
}

Validation Error (422)

{
  "detail": [
    {
      "loc": ["body", "vehicles"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Handling Errors

• Always check meta.status before reading data.
• Branch on the data.type field for 400 errors to show actionable messaging.
• Implement retry logic with backoff for 429 responses.
• Treat 401 and 403 as configuration issues — they will not resolve on retry.