Retries and Idempotency

Use an idempotency key

Generate one UUID for each logical completion request. Send it in Idempotency-Key. If a connection fails before you receive a response, reuse the same key for that retry only.

-H "Idempotency-Key: 98e61b61-dd70-48e3-9ca8-36f0d582adbd"

MaxLabs does not store completion bodies for replay. A reused key therefore returns 409 instead of running and charging the request again. The error code is idempotency_in_progress while the first request is running or idempotency_key_reused after it has completed. The response includes the original request ID. Reconcile that ID in your logs or contact support.

Retry policy

Retry 429, 502, and 503 only when the operation is safe to retry. Honor Retry-After when present. Otherwise use exponential backoff with random jitter, for example 1, 2, 4, and 8 seconds. Set a maximum attempt count and a total deadline.

Do not retry 400, 401, 403, or 404 without changing the request or credentials. Do not assign a new idempotency key to an uncertain request; that can create a second completion.