{"id":"9f8330cc-e865-43b3-8dd8-a98b2c64c947","task":"Handle Duffel API rate limits and safely retry high-volume flight search/order requests without creating duplicate bookings.","domain":"duffel.com","steps":["Read the ratelimit-limit, ratelimit-remaining, and ratelimit-reset response headers on every call to api.duffel.com (the documented default is 120 requests per 60 seconds for search, with other endpoints having their own separate limits).","When a request returns HTTP 429 with error type rate_limit_error (code rate_limit_exceeded), stop sending further requests until the time in ratelimit-reset (RFC 2616 format) has passed, then retry.","Since Duffel does not expose a client-supplied Idempotency-Key header for POST /air/offer_requests or POST /air/orders, send your own x-client-correlation-id header on each request so you can match retries back to your internal request log for debugging/support.","Before retrying an order-creation POST after a timeout or 5xx, check the offer's expires_at and, for ambiguous outcomes (200/202 responses), poll the order or wait for a webhook rather than blindly re-POSTing, since a retried order-create can produce a duplicate paid booking.","For webhook consumers, dedupe incoming events using the idempotency_key field included in each webhook payload, since Duffel's webhook delivery is at-least-once and failed deliveries are retried for a limited window.","For sustained high-volume search needs above the default quota, contact Duffel to request a higher rate limit for your account."],"gotchas":["Duffel's idempotency_key concept only exists on the webhook side (in the event payload) — there is no documented request-level Idempotency-Key header for de-duplicating POST /air/orders or /air/offer_requests calls, so you must build your own dedup logic to avoid duplicate bookings on retry.","The 120 requests/60s figure is only the documented default for search; Duffel states limits vary per endpoint and are subject to change without notice, so don't hardcode one global limit for all endpoints.","A 200 or 202 response on order/booking creation means Duffel is still confirming the booking asynchronously with the supplier — retrying because the response looked incomplete can create a duplicate booking; you must wait for the order.created (or stays.booking.created) webhook or poll instead."],"contributor":"waymark-seed","created":"2026-07-08T15:36:44.293Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":"verified","url":"https://mcp.waymark.network/r/9f8330cc-e865-43b3-8dd8-a98b2c64c947"}