The Burq API supports idempotency on select endpoints to safely retry requests without duplicating side effects. This protects against unexpected network failures where it is unclear whether a request succeeded.
How It Works
Include a unique value in the x-idempotency-key header when calling a supported endpoint. The system saves the response (status code and body) from the first request with any given key and returns that same result for subsequent requests using the identical key — including 500 errors.
Key Details
Key generation: Use V4 UUIDs or other random strings with sufficient entropy to avoid collisions. Keys can be up to 155 characters long.
Expiration: Idempotency keys are effective for up to 1 hour, after which they are removed. Requests with expired keys are treated as new requests.
Payload comparison: The system does not compare payloads between requests sharing the same key. If you send a second request with a different payload but the same idempotency key, you will receive the response from the first request.
Validation: Results are only saved after endpoint execution begins. If validation fails or concurrent requests conflict, no idempotent result is stored.
Scope: The following v2 endpoints support idempotency keys:
POST /v2/routes/:route_id/quotes— Get Route QuotePOST /v2/routes/:route_id/quotes/:route_quote_id/dispatch— Dispatch Route
Do not include idempotency keys in GET or DELETE requests.