For the complete documentation index, see llms.txt. This page is also available as Markdown.

Why am I hitting rate limits during a backfill?

A 429 carrying a provider rate-limit message means the upstream provider's per-user quota is exhausted, not a Terra limit.

A 429 carrying a provider rate-limit message means the upstream provider's per-user quota is exhausted, not a Terra limit. Terra's own API rate limit is very lenient.

Provider quotas vary:

  • Fitbit is the most restrictive, at roughly 150 requests per user per hour.

  • Withings is also restrictive.

  • Apple Health has no provider-side request limit.

  • WHOOP: one Terra request fans out into several WHOOP calls (activity/athlete = 1, sleep = 2, daily = 4), and webhook-triggered fetches count too, so polling plus backfills exhaust the quota quickly.

To mitigate:

  • Prefer webhooks over polling.

  • Avoid concurrent or repeated requests for the same user, and retry only after the window resets.

  • Set retry_if_rate_limited=true so Terra retries and delivers all data later.

  • Use to_webhook=true for large requests. A 504 is expected on large synchronous transfers because of a 30s cutoff.

For Strava, Terra has no direct partnership, so limits are tied to the credentials you obtained from Strava yourself. Request an increase directly from Strava, which they often grant.

Last updated

Was this helpful?