---
title: "Rate limits"
description: "Read your remaining quota from response headers, and back off before you hit 429."
url: "https://nov18-prod-sg.movespot.fyi/guides/rate-limits"
image: "https://nov18-prod-sg.movespot.fyi/_og/d/c_Ocean.takumi,title_Rate+limits,description_~UmVhZCB5b3VyIHJlbWFpbmluZyBxdW90YSBmcm9tIHJlc3BvbnNlIGhlYWRlcnMsIGFuZCBiYWNrIG9mZiBiZWZvcmUgeW91IGhpdCA0Mjku,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiNDQjUzMjQifX19,p_Ii9ndWlkZXMvcmF0ZS1saW1pdHMi,s_Jv2vshoKLAMg85Qb.png"
---

# Rate limits

Read your remaining quota from response headers, and back off before you hit 429.

## [How limits work](#how-limits-work)

Rate limits apply per application, per API. They are enforced with a token bucket: you have a steady allowance per minute, plus a small burst buffer for short spikes.

If you exceed the limit, the API returns `429 Too Many Requests` and the request is not processed.

## [Read the headers](#read-the-headers)

Every response includes your current usage:

| Header                | What it tells you                             |
| :-------------------- | :-------------------------------------------- |
| X-RateLimit-Limit     | Your allowance for the current window         |
| X-RateLimit-Remaining | How many requests you have left               |
| X-RateLimit-Reset     | When the window resets, as a Unix timestamp   |
| Retry-After           | On 429 responses, how long to wait in seconds |

```bash
curl -i "https://api.example.com/v1/orders" \
  -H "Authorization: Bearer $API_KEY"
```

```text
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 597
X-RateLimit-Reset: 1727712000
```

Log these headers in production. A shrinking `X-RateLimit-Remaining` is the earliest warning that your traffic pattern needs work.

## [Handle 429s correctly](#handle-429s-correctly)

When you get a `429`:

1.  Read the `Retry-After` header and wait that long.
2.  Retry the request with exponential backoff as a fallback.
3.  Never retry in a tight loop. It burns quota and delays your own recovery.

Idempotency and retries

If a retried request creates something, send an idempotency key so a timeout can't double the write. See [Idempotent requests](https://nov18-prod-sg.movespot.fyi/guides/idempotency).

## [Design around the limit](#design-around-the-limit)

-   Batch reads where the API allows it, instead of polling one resource at a time.
-   Cache responses that rarely change.
-   Spread scheduled jobs across the window instead of firing them all at midnight.

Need a higher limit? [Search the guides](https://nov18-prod-sg.movespot.fyi/guides), or contact the team that runs these APIs and include your application name and typical request volume.

## [Next steps](#next-steps)

### Idempotent requests

Retry safely after a timeout, so nothing happens twice.

<https://nov18-prod-sg.movespot.fyi/guides/idempotency>

### Errors

Understand error responses and decide which requests to retry.

<https://nov18-prod-sg.movespot.fyi/guides/errors>

### Webhooks

Get notified when resources change instead of polling.

<https://nov18-prod-sg.movespot.fyi/guides/webhooks>