Errors and rate limits

When a request fails, the API returns an HTTP status code and a JSON body with a human-readable message.

What each status means

Status	Meaning	What to do
400 Bad Request	The request is malformed: invalid JSON, a missing parameter or an invalid value.	Fix the request using the message.
401 Unauthorized	Authentication is missing or invalid.	Check your API key and token. See Authentication and request signing.
403 Forbidden	You're authenticated, but the user behind the key isn't allowed to do this.	Check that user's roles.
404 Not Found	The resource doesn't exist, or the URL is wrong.	Check the path and IDs.
405 Method Not Allowed	The endpoint doesn't support that HTTP method.	Use the method shown in the API reference.
409 Conflict	The request conflicts with the current state of the resource.	Fetch the current state, then decide whether to retry.
429 Too Many Requests	You've hit a rate limit.	Back off (see below).
500 Internal Server Error	Something went wrong on Hex Trust's side.	Retry later. If it continues, contact support.
502, 503, 504	A gateway or the service is temporarily unavailable.	Retry later, with backoff.

Rate limits

Rate limits are set per endpoint, per minute, and apply to each API user. If you exceed one, you get 429.

To stay within the limits:

• Spread requests out across each minute, or across several API users.
• Retry with exponential backoff, and don't retry in a tight loop. If a check runs on a schedule anyway, let the next run pick it up.
• Cache data that rarely changes, such as supported assets and chains.
• Use webhooks instead of polling for transaction updates.

If you need a higher limit, contact clients@hextrust.com. Requests are reviewed case by case.