Handle rate limits and 429 Too Many Requests errors

Shipstar enforces per-endpoint rate limits to keep the API reliable for everyone. If you send requests too quickly, you will receive a 429 Too Many Requests response. Understanding the limits and the headers that come with every response makes it straightforward to build integrations that back off gracefully and retry without manual intervention.

Rate limits

Limits are applied per client IP address:

Rate limit headers

Every response — not just 429s — includes headers that tell you exactly where you stand in the current window:

Reading RateLimit-Remaining on each response lets your integration self-throttle before it hits the limit rather than after.

What to do when you receive a 429

1. Read the Retry-After header. This tells you the minimum number of seconds to wait before sending another request. Always respect this value.
2. Wait, then retry. After the Retry-After period has elapsed, retry the request once. Do not retry immediately.
3. Add exponential backoff for repeated 429s. If you receive another 429 after the first retry, double the wait time before each subsequent attempt (for example, 1 s → 2 s → 4 s → 8 s). This prevents your integration from hammering the API as soon as the window resets.
4. Cache responses where possible. Public content endpoints (changelogs, blog posts, KB articles) return content that does not change between publications. Caching those responses client-side reduces the number of requests you need to make.

Tips

• Monitor RateLimit-Remaining proactively and slow down before it reaches zero rather than waiting for a 429.
• If you are bulk-adding mailing list recipients, note that endpoint has a lower limit of 30 requests per minute — pace those calls accordingly.
• The 429 error body also includes a detail field with a human-readable message and a retry_after value in the JSON, which you can use programmatically if you prefer not to parse the header.