Errors

The Muvon API error format, its types, HTTP statuses and the full list of codes.

Errors use HTTP statuses (4xx is about the request, 5xx is on our side) and always the same body:

json

{
  "error": {
    "type": "invalid_request_error",
    "code": "notice_too_short",
    "message": "pickup_at must be at least 30 hours from now",
    "param": "pickup_at",
    "request_id": "req_7e1f0c2a9b8d4e3f"
  }
}

Types

Type	When
`invalid_request_error`	The request has a problem: a missing field, an invalid value, or a business rule doesn't allow it.
`authentication_error`	The key is missing or doesn't work.
`permission_error`	The key works but can't do that.
`rate_limit_error`	Too many requests. See Rate limits.
`idempotency_error`	Problem with the `Idempotency-Key`. See Idempotency.
`api_error`	Failure on our side. Retry with growing waits.

Codes

Code against code, not message: messages may change, codes won't.

HTTP	Code	Type	What it means
400	`parameter_missing`	`invalid_request_error`	A required field is missing (`param` says which).
400	`parameter_invalid`	`invalid_request_error`	A field has a value or format that isn't valid.
400	`invalid_json`	`invalid_request_error`	The body isn't valid JSON.
400	`body_missing`	`invalid_request_error`	That endpoint needs a JSON body.
400	`idempotency_key_invalid`	`invalid_request_error`	The `Idempotency-Key` must be 1 to 255 printable characters, without spaces.
400	`place_not_found`	`invalid_request_error`	That `place_id` doesn't exist. Use one from `GET /places` or send an address.
400	`vehicle_type_not_found`	`invalid_request_error`	That `vehicle_type_id` doesn't exist. See `GET /vehicle-types`.
400	`quote_invalid`	`invalid_request_error`	The quote has no price. Get a new one.
400	`idempotency_key_required`	`invalid_request_error`	`POST /bookings` without an `Idempotency-Key` header.
401	`missing_api_key`	`authentication_error`	No `Authorization: Bearer` header.
401	`invalid_api_key`	`authentication_error`	The key doesn't exist, was revoked, the account is suspended, or it's a live key before live is enabled.
403	`test_mode_only`	`permission_error`	The `/test/…` paths only work with a test key.
404	`resource_missing`	`invalid_request_error`	No booking or quote with that id or code for your account and mode.
409	`quote_expired`	`invalid_request_error`	The quote expired. Get a new one.
409	`quote_used`	`invalid_request_error`	That quote was already booked.
409	`cancel_window_closed`	`invalid_request_error`	Less than 24 h before pickup. Contact Muvon.
409	`booking_not_payable`	`invalid_request_error`	Sandbox: a cancelled booking can't be paid.
409	`booking_not_cancellable`	`invalid_request_error`	The ride is under way, finished or already cancelled.
409	`invalid_status_transition`	`invalid_request_error`	Sandbox: that status doesn't follow the current one.
409	`idempotency_conflict`	`idempotency_error`	The same `Idempotency-Key` was used with a different body.
422	`notice_too_short`	`invalid_request_error`	Pickup is less than 30 h away, or less than the vehicle's notice.
422	`same_origin_destination`	`invalid_request_error`	Origin and destination are the same place.
422	`route_too_long`	`invalid_request_error`	The trip is longer than 330 km.
422	`route_not_priceable`	`invalid_request_error`	We couldn't work out a route between those points.
422	`passengers_out_of_range`	`invalid_request_error`	No vehicle (or the one you asked for) carries that many people.
422	`too_many_bags`	`invalid_request_error`	The bags don't fit in the vehicle.
422	`hours_out_of_range`	`invalid_request_error`	For `hourly`, `hours` must be 1 to 12.
422	`extra_unavailable`	`invalid_request_error`	That extra doesn't exist or isn't sold through the API.
422	`option_unavailable`	`invalid_request_error`	The `vehicle_type_id` isn't one of the quote's options.
413	`body_too_large`	`invalid_request_error`	The body is larger than 32 KB.
429	`rate_limited`	`rate_limit_error`	Too many requests this minute. Wait what `Retry-After` says.
500	`internal_error`	`api_error`	Something failed on our side. Retry; if it persists, send the `request_id`.
503	`not_configured`	`api_error`	The service isn't available right now. Retry later.
503	`pricing_unavailable`	`api_error`	No rates loaded to quote with. Retry later.

{ "error": { "type": "invalid_request_error", "code": "notice_too_short", "message": "pickup_at must be at least 30 hours from now", "param": "pickup_at", "request_id": "req_7e1f0c2a9b8d4e3f" } }

Types

Type	When
`invalid_request_error`	The request has a problem: a missing field, an invalid value, or a business rule doesn't allow it.
`authentication_error`	The key is missing or doesn't work.
`permission_error`	The key works but can't do that.
`rate_limit_error`	Too many requests. See Rate limits.
`idempotency_error`	Problem with the `Idempotency-Key`. See Idempotency.
`api_error`	Failure on our side. Retry with growing waits.

Codes

Code against code, not message: messages may change, codes won't.

HTTP	Code	Type	What it means
400	`parameter_missing`	`invalid_request_error`	A required field is missing (`param` says which).
400	`parameter_invalid`	`invalid_request_error`	A field has a value or format that isn't valid.
400	`invalid_json`	`invalid_request_error`	The body isn't valid JSON.
400	`body_missing`	`invalid_request_error`	That endpoint needs a JSON body.
400	`idempotency_key_invalid`	`invalid_request_error`	The `Idempotency-Key` must be 1 to 255 printable characters, without spaces.
400	`place_not_found`	`invalid_request_error`	That `place_id` doesn't exist. Use one from `GET /places` or send an address.
400	`vehicle_type_not_found`	`invalid_request_error`	That `vehicle_type_id` doesn't exist. See `GET /vehicle-types`.
400	`quote_invalid`	`invalid_request_error`	The quote has no price. Get a new one.
400	`idempotency_key_required`	`invalid_request_error`	`POST /bookings` without an `Idempotency-Key` header.
401	`missing_api_key`	`authentication_error`	No `Authorization: Bearer` header.
401	`invalid_api_key`	`authentication_error`	The key doesn't exist, was revoked, the account is suspended, or it's a live key before live is enabled.
403	`test_mode_only`	`permission_error`	The `/test/…` paths only work with a test key.
404	`resource_missing`	`invalid_request_error`	No booking or quote with that id or code for your account and mode.
409	`quote_expired`	`invalid_request_error`	The quote expired. Get a new one.
409	`quote_used`	`invalid_request_error`	That quote was already booked.
409	`cancel_window_closed`	`invalid_request_error`	Less than 24 h before pickup. Contact Muvon.
409	`booking_not_payable`	`invalid_request_error`	Sandbox: a cancelled booking can't be paid.
409	`booking_not_cancellable`	`invalid_request_error`	The ride is under way, finished or already cancelled.
409	`invalid_status_transition`	`invalid_request_error`	Sandbox: that status doesn't follow the current one.
409	`idempotency_conflict`	`idempotency_error`	The same `Idempotency-Key` was used with a different body.
422	`notice_too_short`	`invalid_request_error`	Pickup is less than 30 h away, or less than the vehicle's notice.
422	`same_origin_destination`	`invalid_request_error`	Origin and destination are the same place.
422	`route_too_long`	`invalid_request_error`	The trip is longer than 330 km.
422	`route_not_priceable`	`invalid_request_error`	We couldn't work out a route between those points.
422	`passengers_out_of_range`	`invalid_request_error`	No vehicle (or the one you asked for) carries that many people.
422	`too_many_bags`	`invalid_request_error`	The bags don't fit in the vehicle.
422	`hours_out_of_range`	`invalid_request_error`	For `hourly`, `hours` must be 1 to 12.
422	`extra_unavailable`	`invalid_request_error`	That extra doesn't exist or isn't sold through the API.
422	`option_unavailable`	`invalid_request_error`	The `vehicle_type_id` isn't one of the quote's options.
413	`body_too_large`	`invalid_request_error`	The body is larger than 32 KB.
429	`rate_limited`	`rate_limit_error`	Too many requests this minute. Wait what `Retry-After` says.
500	`internal_error`	`api_error`	Something failed on our side. Retry; if it persists, send the `request_id`.
503	`not_configured`	`api_error`	The service isn't available right now. Retry later.
503	`pricing_unavailable`	`api_error`	No rates loaded to quote with. Retry later.