# Errors > The Maxmove API error format, every error code with what to do about it, and which errors to retry. Errors use HTTP status codes and one JSON shape: ```json { "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](https://maxmove.com/en/developers/docs/support). New error codes can appear within v1. Handle unknown codes by their HTTP status. ## What to retry | Errors | What to do | | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `429` | Wait the number of seconds in `Retry-After`, then retry. | | `500`, `502`, `503`, network errors, timeouts | Retry with backoff. For `POST /v1/deliveries` and `POST /v1/fleet/orders`, reuse the same `Idempotency-Key` and body. | | `409 request_in_progress` | Retry the same request a moment later. | | `402` | Settle your workspace's open statements, then retry. | | Other `4xx` | Don't retry unchanged. Fix the request, or request a new quote for `quote_expired` and `quote_mismatch`. | See [Idempotency](https://maxmove.com/en/developers/docs/concepts/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](https://maxmove.com/en/developers/docs/concepts/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](https://maxmove.com/en/developers/docs/coverage). ### `vehicle_does_not_fit` The chosen vehicle type cannot carry the items. Choose a larger vehicle type. See [Items and vehicle fit](https://maxmove.com/en/developers/docs/guides/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](https://maxmove.com/en/developers/docs/webhooks/events). ## 401 Unauthorized ### `missing_api_key` The request has no key in `x-api-key` or `Authorization`. See [Authentication](https://maxmove.com/en/developers/docs/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](https://maxmove.com/en/developers/docs/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](https://maxmove.com/en/developers/docs/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](https://maxmove.com/en/developers/docs/guides/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](https://maxmove.com/en/developers/docs/guides/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](https://maxmove.com/en/developers/docs/concepts/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. --- Source: https://maxmove.com/en/developers/docs/concepts/errors