Rate Limits

Applies to the Forward, Reverse, and Exchange APIs on the client gateway. Hyperlocal and Quick Commerce run on separate backends and may throttle differently.

Shadowfax throttles per client. Exact limits are set per account and aren't published here — confirm yours with your account manager before building anything poll-heavy.

Handling 429

When you're throttled you get an HTTP 429 with the responseCode/responseMsg envelope:

Code
{ "responseMsg": "Request Blocked Temporarily", "responseCode": 429 }

Treat this as expected, not exceptional. Two things to know:

• Throttling can trigger at low request volumes, well below any per-minute figure you may have been quoted. Don't size your polling against an assumed ceiling.
• Recovery is not immediate. A block can persist for longer than a minute, so a tight retry loop will keep failing. Back off exponentially — start at a few seconds and cap at 60s.

Limits differ between staging and production, so throughput you get while testing is not a guide to what production will allow.

Avoid Polling Where You Can

Most 429s come from polling tracking endpoints. Two ways to avoid it entirely:

• Webhooks — status updates are pushed to you in real time, and cost no quota at all. This is the recommended integration for order status. See the callbacks/webhooks page for your product.
• Bulk tracking — where a bulk endpoint exists, fetch many AWBs in one call instead of one call per AWB.

If you must poll, poll on a schedule proportional to how fast the state actually changes — an order in transit does not need checking every few seconds.

Best Practices

• Prefer webhooks over polling — faster updates, zero quota.
• Use bulk endpoints when checking multiple AWBs.
• Implement exponential backoff on both 429 and 5xx. Start at 1s, cap at 60s.
• Cache serviceability results — pincode coverage changes infrequently.