Rate limits & errors

A free API key is required, and every account gets the same daily allowance. Honest clients get the headers they need to self-throttle.

Authentication

The public /api/v1/* endpoints require an API key — requests without a valid key are rejected with 401 (only /api/v1/health is open).

Create a free API key in the AllNutrition web app under Settings → API keys and send it as Authorization: Bearer ank_… (or X-API-Key: ank_…). You get live usage tracking in settings, and your /api/v1/ask questions are saved to your private Ask history in the app — visible only to you, never shared (opt out per request with save_session: false, or turn saving off account-wide in settings, where you can also hide them from history).

If you need higher volume beyond the free allowance, email support@allnutrition.info.

The limit

Scope	Limit	Window
Per account (all its keys combined), across all `/api/v1/*` endpoints	10 requests	UTC calendar day (resets at 00:00 UTC)

The allowance is the same for every account for now, and is shared between /api/v1/ask and /api/v1/references/search. /api/v1/health is not rate limited.

Headers on every response

Both successful and 429 responses include:

RateLimit-Limit: 10
RateLimit-Remaining: 7
RateLimit-Reset: 41218     # seconds until the window resets

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1746489600   # absolute unix timestamp (UTC)

We send both the draft IETF RateLimit-* headers (delta-seconds reset) and the legacy X-RateLimit-* headers (absolute unix timestamp reset). Use whichever your client supports.

The 429 response

When your account's daily allowance is spent:

HTTP/1.1 429 Too Many Requests
Retry-After: 41218
RateLimit-Limit: 10
RateLimit-Remaining: 0
RateLimit-Reset: 41218
Content-Type: application/json

{
  "detail": {
    "error": "rate_limit_exceeded",
    "message": "Daily API limit of 10 requests per account exceeded. Resets at 2026-05-09T00:00:00+00:00.",
    "limit": 10,
    "remaining": 0,
    "reset_at": 1746489600
  }
}

Recommended client behaviour

Read RateLimit-Remaining on every successful response and stop sending when it hits zero.
On 429, honour Retry-After (delta seconds). Do not retry sooner.
For agentic loops, cache answers — most nutrition questions are repeated across users.

Other error codes

Status	When you see it	Action
`400`	Empty `question` / `query`, or fields exceeding limits (max 1000 chars).	Fix the payload. Don't retry as-is.
`401`	The API key is missing, invalid, or revoked (all `/api/v1/*` requests need one, except `/health`).	Create or check your key under Settings → API keys and send it as `Authorization: Bearer ank_…`.
`500`	Unexpected server-side failure.	Retry with exponential backoff (e.g. 1s → 2s → 4s, max 3 attempts).
`503`	Upstream LLM provider exhausted or unavailable.	Retry after 30–60 seconds.

Going beyond the public limit

For production integrations with heavier usage, partner SLAs, or per-account analytics, request a higher-volume tier: support@allnutrition.info.