Rate Limits & Errors

    Understand quotas, status codes, and how to handle errors gracefully.

    Rate limits

    TierDaily limitPer key
    Free10,000 calls/dayYes

    Limits reset at midnight UTC. Usage counts are tracked per API key, not per account. You can monitor your current usage on the dashboard.

    Rate limit headers

    Every response includes rate limit headers:

    HeaderDescription
    X-RateLimit-LimitDaily request quota
    X-RateLimit-RemainingRequests remaining today
    X-RateLimit-ResetUnix timestamp when the quota resets

    Error responses

    Errors return JSON with a consistent structure:

    {
  "error": {
    "code": 429,
    "message": "Rate limit exceeded. Resets at midnight UTC."
  }
}

    Status codes

    CodeMeaningAction
    200 Success Parse the response body
    403 Invalid or missing API key Check that the x-api-key header or api_key query param is present and valid
    404 No data for cell or zone Verify the H3 index is resolution 6, or the zone ID is valid
    429 Rate limit exceeded Back off and retry after the reset time in X-RateLimit-Reset

    Best practices

    Next: Attribution →