Maxmove LogoDocs

Errors

The Maxmove API error format, every error code with what to do about it, and which errors to retry.

View as Markdown

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#

ErrorsWhat to do
429Wait the number of seconds in Retry-After, then retry.
500, 502, 503, network errors, timeoutsRetry with backoff. For POST /v1/deliveries and POST /v1/fleet/orders, reuse the same Idempotency-Key and body.
409 request_in_progressRetry the same request a moment later.
402Settle your workspace's open statements, then retry.
Other 4xxDon't retry unchanged. Fix the request, or request a new quote for quote_expired and quote_mismatch.

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.

Did this answer your question?