Response headers

All Hiro APIs return response headers that provide important information about rate limits and usage quotas.

The following headers are returned with every API response:

Terminal

$ curl -I https://api.hiro.so/extended/v1/info -H 'x-api-key: your-api-key'

Header	Description
`ratelimit-limit`	The rate limit ceiling for that endpoint
`ratelimit-remaining`	The number of requests left for the current window
`ratelimit-reset`	The time when the rate limit window resets (Unix timestamp)
`retry-after`	Time to wait before retrying (only present when rate limited)

Stacks service headers

When calling Stacks-related endpoints (Stacks Blockchain API, Token Metadata API, etc), you'll receive:

// Example: Fetching Stacks account info
const response = await fetch('https://api.hiro.so/extended/v1/address/SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWP/assets', {
  headers: { 'x-api-key': apiKey }
});

console.log(response)

// Example response headers:
// x-ratelimit-cost-stacks: 1 // !mark
// x-ratelimit-limit-stacks-minute: 5000
// x-ratelimit-remaining-stacks-minute: 4999

Header	Description
`x-ratelimit-cost-stacks`	The quota cost for this specific request
`x-ratelimit-limit-stacks-second`	Per-second limit for Stacks services
`x-ratelimit-remaining-stacks-second`	Remaining requests this second
`x-ratelimit-limit-stacks-minute`	Per-minute limit for Stacks services
`x-ratelimit-remaining-stacks-minute`	Remaining requests this minute
`x-ratelimit-limit-stacks-month`	Monthly limit for Stacks services
`x-ratelimit-remaining-stacks-month`	Remaining requests this month

The x-ratelimit-cost-stacks header shows the exact quota cost for each request, which may vary based on the endpoint and parameters used.

Response headers

Stacks service headers

Further reading

How is this guide?