Skip to main content
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: 
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 codeNameDescription
400bad_dataThe request body is malformed or contains invalid fields. Fix the request before retrying.
401UnauthorizedThe request is missing valid authentication credentials. Check the Authorization header and signed JWT.
403DeniedThe credentials are valid, but the team or sender does not have access to perform the requested action.
429Rate limit exceededYou have sent more than 500 requests in the current minute. Wait and retry with exponential backoff.
500Server errorAn 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.
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.