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.
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.
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.
Request IDs
Every response from the Heymarket API includes an X-Request-Id header:
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.
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.
If you receive repeated 500 responses, include the X-Request-Id header value when you contact support so the team can investigate.
