Errors

Every refusal has the same body:

{
  "code": "quote.expired",
  "message": "This quote has expired. Request a new one."
}

Branch on code. It is stable and meant for your code. message is for a person reading a log and may change at any time.

Status codes

Status	Meaning	Retry?
200, 201, 204	Done.	—
401	The key or the secret is wrong or missing.	No. Fix the credential.
404	No such resource — or not yours, which gets the same answer.	No.
409	request.in_progress: an identical booking is still running.	Yes, after a moment, with the same Idempotency-Key.
422	We understood the request and are declining it. The code says why.	Not as it is. Change the request.
429	Too many requests. See Retry-After.	Yes, after that many seconds.
503	A service behind the API is briefly unavailable.	Yes, with back-off.
5xx	Something went wrong on our side.	Yes, with back-off — and for bookings, with the same Idempotency-Key.

422 rather than 400 is deliberate: the request was well formed, and a different request — a new quote, a different vehicle — would succeed. Retrying the same one won’t.

Codes you’ll meet

The request

code
request.malformed	A required part of the body is missing.
request.invalid_pickup, request.invalid_dropoff, request.invalid_point	Coordinates that aren’t a point on Earth.
request.unknown_vehicle, request.invalid_vehicle	Not one of bicycle, electric_bicycle, motorcycle, car, van.
request.invalid_weight	A negative weight_grams.
request.invalid_quote_id	quote_id isn’t a well-formed identifier.
request.invalid_stop	A contact is missing its address, name or a usable phone number.
request.unknown_status	A status in ?status= that doesn’t exist.
request.missing_idempotency_key	A booking without Idempotency-Key.
request.idempotency_key_reused	That key was used for a different request.
request.in_progress	That key’s first request is still running.

Pricing

code
pricing.origin_not_covered, pricing.destination_not_covered	Outside the areas we serve.
pricing.no_route	No route between the points for that vehicle.
pricing.vehicle_not_available	That vehicle isn’t offered in your market.
pricing.no_rule_matches, pricing.no_weight_bracket	No price covers this journey or weight. Tell us — it’s a gap in your price list.
quote.not_found, quote.expired, quote.already_used	The quote can’t be booked: unknown, more than ten minutes old, or booked already.

Booking

code
job.scheduled_in_past	scheduled_for has passed.
order.item_invalid	An item with no name, a negative price or a quantity under one.
order.discount_negative, order.discount_exceeds_items	The discount is below zero or more than the items.
order.total_negative	items_total_minor is below zero.

Webhooks

code
webhook.endpoint_not_secure	The URL isn’t https.
webhook.endpoint_not_absolute	The URL isn’t a full address.
webhook.unknown_event	An event name we don’t send.
webhook.already_registered	That URL is registered already.
webhook.not_found	No such endpoint, or not yours.

Payments

code
payment.malformed_card	The provider_ref isn’t a card reference — or is a raw card number.
payment.card_expired	The card has expired.
payment.method_not_found	No such card, or not yours.