Skip to main content

​
Overview

The beaconcha.in API uses rate limiting to ensure fair usage and maintain service quality for all users. Rate limits vary by subscription tier and are enforced across multiple time windows.

​
Rate Limit Headers

Every API response includes headers that show your current rate limit status:

​
Primary Headers

HeaderDescriptionExample
ratelimit-limitRequests allowed per window1
ratelimit-remainingRequests remaining in current window0
ratelimit-resetSeconds until the window resets1
ratelimit-windowThe time window typesecond
ratelimit-validapikeyWhether your API key is validtrue

​
Extended Headers

The API also returns detailed limits for each time window:
HeaderDescription
x-ratelimit-limit-secondRequests allowed per second
x-ratelimit-limit-minuteRequests allowed per minute
x-ratelimit-limit-hourRequests allowed per hour
x-ratelimit-limit-dayRequests allowed per day
x-ratelimit-limit-monthRequests allowed per month
x-ratelimit-remaining-secondRemaining requests this second
x-ratelimit-remaining-minuteRemaining requests this minute
x-ratelimit-remaining-hourRemaining requests this hour
x-ratelimit-remaining-dayRemaining requests today
x-ratelimit-remaining-monthRemaining requests this month

​
Checking Your Rate Limits

Make any API request and inspect the response headers to see your current limits: 
curl -s -D - -o /dev/null --request POST \
  --url https://beaconcha.in/api/v2/ethereum/validators/rewards-aggregate \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "chain": "mainnet",
    "validator": { "validator_identifiers": [1] },
    "range": { "evaluation_window": "24h" }
  }'
Example Response Headers: 
ratelimit-limit: 1
ratelimit-remaining: 0
ratelimit-reset: 1
ratelimit-window: second
ratelimit-validapikey: true
x-ratelimit-limit-second: 1
x-ratelimit-limit-minute: 1000
x-ratelimit-limit-hour: 1000
x-ratelimit-limit-day: 1000
x-ratelimit-limit-month: 1000
x-ratelimit-remaining-second: 0
x-ratelimit-remaining-minute: 972
x-ratelimit-remaining-hour: 972
x-ratelimit-remaining-day: 972
x-ratelimit-remaining-month: 972

​
Handling Rate Limit Errors

When the rate limit is exceeded, the API returns a 429 Too Many Requests status code. To handle this correctly, implement retry logic with a dynamic delay: immediately pause outgoing requests and wait for the duration specified in the ratelimit-reset header before attempting the request again.

​
Rate Limits by Plan

Rate limits vary by subscription tier:
PlanPrice/moFeaturesLimit/secLimit/mo
Free0€Basic11,000
Hobbyist59€*Basic1—
Business99€*Basic2—
Scale399€*Basic & Pro 💎5—
EnterpriseContact usBasic & Pro 💎Contact us—
*Prices shown are for annual billing, excluding VAT
Pro 💎 features include premium validator selectors (withdrawal address, deposit_address) and are available on Scale and Enterprise plans.
View current pricing at beaconcha.in/pricing. Your actual limits are always available in the response headers.

​
Best Practices

Monitor Headers

Check x-ratelimit-remaining-* headers before making bulk requests to avoid hitting limits.

Use Backoff

Implement exponential backoff when receiving 429 errors to gracefully handle rate limits.

Batch with Dashboards

Use dashboard_id to query multiple validators in a single request instead of individual calls.