> ## Documentation Index
> Fetch the complete documentation index at: https://developers.heymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits and request IDs

> Understand the Heymarket API's 500 req/min rate limit, how to use X-Request-Id when contacting support, and how to handle HTTP error codes.

The Heymarket API enforces rate limits to keep the service stable. If your integration sends requests too quickly, the API returns an error and you must slow down before retrying. Every response also includes a request ID that helps Heymarket support trace individual calls.

## Rate limit

The public API limit is **500 requests per minute**. When you exceed this limit, the API responds with HTTP `429 Too Many Requests`.

<Tip>
  Use exponential backoff when you receive a `429` response. Wait briefly, retry, and increase the wait time after each failed retry until the request succeeds or reaches your retry limit.
</Tip>

<Warning>
  Be careful when retrying write requests. If a request may have reached Heymarket before your client received an error, retrying can create duplicate side effects unless the endpoint supports an idempotency field such as `local_id`.
</Warning>

## Request IDs

Every response from the Heymarket API includes an `X-Request-Id` header:

```text theme={null}
X-Request-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

Log this value alongside your own application logs. When you contact Heymarket support about an issue, include the `X-Request-Id` so the team can find the exact request.

## Error codes

The table below covers the most common HTTP status codes returned by the API.

| Status code | Name                | Description                                                                                                                                                |
| ----------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`       | `bad_data`          | The request body is malformed or contains invalid fields. Fix the request before retrying.                                                                 |
| `401`       | Unauthorized        | The request is missing valid authentication credentials. Check the `Authorization` header and signed JWT.                                                  |
| `403`       | Denied              | The credentials are valid, but the team or sender does not have access to perform the requested action.                                                    |
| `429`       | Rate limit exceeded | You have sent more than 500 requests in the current minute. Wait and retry with exponential backoff.                                                       |
| `500`       | Server error        | An unexpected error occurred on the Heymarket side. Retry the request after a brief delay. If the error persists, contact support with the `X-Request-Id`. |

<Note>
  A `400` error will not resolve by retrying. Read the error response body for details about which field failed validation, fix your request, and then send it again.
</Note>

<Warning>
  If you receive repeated `500` responses, include the `X-Request-Id` header value when you contact support so the team can investigate.
</Warning>