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:

| Endpoint category | Limit | | --- | --- | | Public content endpoints | 100 requests/minute | | Authenticated endpoints | 100 requests/minute | | Add mailing list recipients | 30 requests/minute |

Rate limit headers

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

| Header | What it means | | --- | --- | | RateLimit-Limit | Total requests allowed in the current window | | RateLimit-Remaining | Requests you still have in the current window | | RateLimit-Reset | Seconds until the window resets | | RateLimit-Policy | The quota policy, e.g. 100;w=60 | | Retry-After | Seconds to wait before retrying (included on 429 responses) |

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.