Errors

Errors use HTTP status codes and one JSON shape:

{
  "error": {
    "code": "quote_expired",
    "message": "The quote has expired. Request a new quote and retry.",
    "doc_url": "https://maxmove.com/en/developers/docs/concepts/errors#content-quote-expired"
  },
  "request_id": "7c9e6679-…"
}

Branch on error.code. The message is for people and may change. doc_url links to the code's entry on this page. Send the request_id when you contact support.

New error codes can appear within v1. Handle unknown codes by their HTTP status.

What to retry#

See Idempotency for a retry example.

400 Bad Request#

invalid_request#

A field is missing or invalid. The message names the field. Fix the request before you send it again.

quote_mismatch#

The request differs from the quote you passed in quote_id: the route, vehicle type, extras, items, or scheduled_at. Send exactly the quoted values, or request a new quote. See Quotes.

quote_not_found#

No quote with this quote_id exists for this key and mode. Test and live quotes are separate.

quote_expired#

The quote has expired. Quotes are valid for about 5 minutes. Request a new quote and create the delivery with it.

service_area_unavailable#

The pickup, the dropoff, or a stop is outside the Maxmove service area. See Coverage.

vehicle_does_not_fit#

The chosen vehicle type cannot carry the items. Choose a larger vehicle type. See Items and vehicle fit.

invalid_items#

The items cannot be evaluated. Check their quantities, weights, and dimensions.

missing_idempotency_key#

The Idempotency-Key header is missing. POST /v1/deliveries and POST /v1/fleet/orders require it.

invalid_idempotency_key#

The Idempotency-Key header is longer than 255 characters.

invalid_page_token#

The page_token is not valid. Pass the next_page_token from the previous page unchanged.

invalid_webhook_url#

The webhook URL is not a public HTTPS URL. See Webhook events.

401 Unauthorized#

missing_api_key#

The request has no key in x-api-key or Authorization. See Authentication.

invalid_api_key#

The key is invalid, expired, or revoked. Create a new key in the dashboard.

402 Payment Required#

These codes only occur when you create a live delivery, not on quotes. See Billing.

invoice_credit_limit_exceeded#

The delivery would exceed your workspace's credit limit. Settle open statements or contact support about the limit.

invoice_statement_overdue#

An invoice statement is overdue. Pay it to book live deliveries again.

403 Forbidden#

permission_denied#

The key lacks the permission for this request. Create a key with the permission you need.

api_access_disabled#

API access is not part of your workspace's plan.

invoice_billing_not_enabled#

Your workspace is not approved for invoice billing yet, so it can't create live deliveries. Quotes still work. See Billing.

fleet_key_required#

Fleet orders need a key of a fleet workspace.

live_key_required#

Fleet orders always create real orders and need a live key. Test keys get this error on create and read.

fleet_orders_not_available#

Your fleet plan does not include order intake.

pod_not_available#

Your plan does not include proof of delivery.

404 Not Found#

not_found#

The resource does not exist for this key and mode. Test and live resources are separate.

no_proof_of_delivery#

The courier has not submitted proof of delivery yet. See Proof of delivery.

409 Conflict#

not_cancellable#

The delivery can no longer be cancelled, because the courier has already picked up the goods. See Cancellations.

conflict#

The current state does not allow this request. The message explains why.

idempotency_key_reused#

The Idempotency-Key was already used with a different body. Use a new key for a new request.

request_in_progress#

The first request with this Idempotency-Key is still running. Retry the same request a moment later.

duplicate_external_id#

Another delivery already uses this external_id.

endpoint_limit_reached#

The workspace has the maximum number of webhook endpoints. Delete one you no longer use.

endpoint_disabled#

The webhook endpoint is disabled.

429 Too Many Requests#

rate_limited#

Too many requests. Wait the number of seconds in Retry-After, then retry. See Rate limits.

5xx Server errors#

internal_error#

An unexpected error (HTTP 500). Retry with backoff and the same Idempotency-Key. If it persists, contact support with the request_id.

verification_failed#

An unexpected verification error (HTTP 500). Retry with backoff and the same Idempotency-Key.

upstream_error#

An internal service failed (HTTP 502). Retry shortly.

service_unavailable#

The API is temporarily unavailable (HTTP 503). Retry shortly.