API reference/API rate limits & AI usage budget
updated 2026-07-12
API reference

API rate limits & AI usage budget

Request rate limits per API key, the 429 + Retry-After contract, and the 402 you'll see if AI-backed calls exceed the monthly AI budget.

Advanced  The Protocol REST API applies two independent limits to protect the platform: a request rate limit on every API key, and a monthly AI usage budget on AI-backed endpoints. Both are enforced server-side — no setup required — but your integration should handle the status codes below gracefully.

Request rate limits

Each API key (pk_live_…) is limited independently of every other key on your account or any other account:

Window Limit
Per minute 1,000 requests
Per hour 10,000 requests

Go over either window and the API returns:

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

Retry-After is the number of seconds to wait before retrying. Back off for at least that long — retrying immediately just consumes more of the same window.

Scope: these limits apply only to requests authenticated with a pk_live_ API key. Your own dashboard/mobile sessions (JWT-based) and an AI assistant connected via the AI Agent MCP connector are on separate, unrelated limits and are not affected by this table.

AI usage budget (402)

Some endpoints call out to an AI model on your behalf (e.g. AI-assisted content generation, coach-chat, meal/photo analysis). Every account has a monthly AI usage budget, shared across all AI-backed features regardless of plan:
Monthly AI budget $100
Resets Start of each monthly billing period

If a call to an AI-backed endpoint would exceed your remaining budget for the current period, the API returns:

HTTP/1.1 402 Payment Required

{
  "success": false,
  "message": "AI usage limit reached for this billing period",
  "data": null
}

Non-AI endpoints are unaffected — a 402 only ever comes from an endpoint that calls an AI model. If you’re consistently hitting this limit, reach out — usage-based overage is available on request.

Handling both in your integration

  • Treat 429 as retryable: read Retry-After, wait, then retry the same request.
  • Treat 402 as not immediately retryable: it clears at the next billing period, not on a timer — retrying sooner won’t help.
  • Both are ordinary JSON error responses ({ success: false, message, data: null }), same shape as any other API error — no special parsing needed beyond checking the status code.