Maxmove LogoDocs

Die Entwicklerdokumentation ist auf Englisch verfügbar.

Idempotency

Retry delivery and fleet order requests safely with the Idempotency-Key header, without creating duplicates.

Als Markdown ansehen

Network errors and timeouts leave you unsure whether a request reached Maxmove. To retry safely, POST /v1/deliveries and POST /v1/fleet/orders require an Idempotency-Key header of 1 to 255 characters. Use a value that identifies the order in your system, for example your order id.

curl -X POST https://api.maxmove.com/v1/deliveries \
  -H "x-api-key: $MAXMOVE_KEY" -H "content-type: application/json" \
  -H "Idempotency-Key: order-4711" \
  -d @delivery.json

How retries behave#

For POST /v1/deliveries:

SituationResponse
First successful request201 with the new delivery.
Retry with the same key and body200 with the original delivery and the header Idempotent-Replayed: true.
Same key with a different body409 idempotency_key_reused.
Retry while the first request is still running409 request_in_progress. Retry a moment later.
Header missing400 missing_idempotency_key.
Header longer than 255 characters400 invalid_idempotency_key.

For POST /v1/fleet/orders, the header rules are the same, but a retry with the same key answers 201 with the existing order. Fleet orders don't send Idempotent-Replayed.

After a timeout, a network error, or a 5xx answer, retry with the same key and the same body. Don't generate a new key for a retry, or you may create a second delivery.

Idempotency keys belong to one mode: the same key used with a test key and a live key creates two independent resources.

Retry with backoff#

async function createDelivery(body: unknown, idempotencyKey: string) {
  for (let attempt = 1; attempt <= 5; attempt++) {
    try {
      const res = await fetch('https://api.maxmove.com/v1/deliveries', {
        method: 'POST',
        headers: {
          'x-api-key': process.env.MAXMOVE_KEY!,
          'content-type': 'application/json',
          'Idempotency-Key': idempotencyKey,
        },
        body: JSON.stringify(body),
      });
      const retryable = res.status === 429 || res.status >= 500 ||
        (res.status === 409 && (await res.clone().json()).error?.code === 'request_in_progress');
      if (!retryable) return res;
    } catch {
      // Network error: retry with the same key and body.
    }
    await new Promise((resolve) => setTimeout(resolve, 2 ** attempt * 500));
  }
  throw new Error('Delivery creation did not succeed after 5 attempts');
}

For 429 answers, wait at least the number of seconds in the Retry-After header. See Rate limits.

external_id#

external_id on a delivery is your own reference and is unique per mode. It is not a replacement for the Idempotency-Key: a second delivery with the same external_id answers 409 duplicate_external_id, even if the body is identical.

Hat das Ihre Frage beantwortet?