Rate limits

NutritionSignals applies rate limits to protect the platform and ensure consistent performance for everyone. This page explains how rate limiting works and how to handle it safely in production.

Exact limits may vary by plan and can change over time. Responses may include headers like Retry-After (and, if available, rate-limit/quota headers) to help you understand remaining capacity and reset timing.

What to expect

Most requests complete normally. When you exceed a limit, the API responds with:

429 — Rate limited (too many requests in a short window)

See Errors for the full error format and examples.

Rate limits vs plan limits

A few different “limits” can look similar:

Rate limit (429) — too many requests too quickly. Retry with backoff.
Plan/quota limit (402 or 429) — you’ve reached a plan quota (if your plan enforces quotas). Upgrade or wait for reset.
Access restriction (403) — your API key is valid, but your plan doesn’t include that endpoint or the key is disabled.

If you’re unsure which one you hit, check the JSON error type/message and any Retry-After header.

Recommended client behavior

1) Use exponential backoff

When you receive a 429, retry with exponential backoff and jitter to avoid synchronized retries.

Suggested strategy:

Start at 500ms
Double each retry: 500ms → 1s → 2s → 4s → 8s
Add small random jitter (±20%)
Stop after 5–7 retries and surface a user-friendly error

2) Respect retry hints

If the API returns a Retry-After header, treat it as the primary signal for when to retry.

HTTP/1.1 429 Too Many Requests
Retry-After: 2

3) Avoid bursty traffic

If you need to resolve many items (for example, importing a pantry or scanning a receipt), throttle requests on the client:

Limit concurrent requests (for example, 2–5 at a time)
Queue the rest
Use backoff when you hit 429

Example backoff helpers

# Retry using curl flags (constant-delay).
# For true exponential backoff in shell scripts, wrap curl in a loop and double the delay after each 429.
curl -sS \
  --retry 8 \
  --retry-all-errors \
  --retry-delay 1 \
  --retry-max-time 60 \
  --retry-on-http-error 429,500,502,503,504 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"text":"Chobani Greek Yogurt, strawberry, 5.3 oz","country":"DE"}' \
  "https://api.nutritionsignals.com/v1/foods/resolve"

The cURL example uses a constant retry delay. For true exponential backoff in shell scripts, wrap curl in a loop and double the delay after each 429.

Errors

429 — Rate limited
402/403 — Plan or access restriction (upgrade or change key/plan)
401 — Missing/invalid API key (often confused with rate limiting)
5xx — Server error (retry with backoff)

Read Errors