Credits & limits

MealCP bills per request with credits, throttles with a per-minute rate limit, and tells you both states over HTTP.

Credit costs

Endpoint	Key required	Cost
`GET /v1/search`	yes	10-50 - flat 10 for the default 24-row page, then 0.5 credits per requested row (50 at `page_size=100`)
`GET /v1/products`	yes	50 per page
`GET /v1/products/{product_id}`	yes	2
`GET /v1/prices/{product_id}`	yes	2
`GET /v1/prices/{product_id}/observations`	yes	50 per 100-observation page
`GET /v1/me`	yes	0
`GET /v1/stores`	yes	0
`GET /v1/coverage`	no	0
`GET /v1/categories`	no	0
`GET /v1/tags`	no	0
`GET /health`, `GET /openapi.json`	no	0

Credits scale with the data a request can return, so every bulk path - a wide search page, a catalogue walk, an observations export - costs roughly 0.5 credits per row. Interactive use stays cheap: a default-page search is a flat 10, and single lookups cost 2. On search, page_size up to 24 costs a flat 10; above that each requested row adds 0.5 credits, so page_size=25 costs 13 and page_size=100 costs 50.

Your allowance

Beta key: 1,500 credits / 30 days, 300 req/min per key - beta keys are no longer issued; existing keys keep working, and the launch date lands on Discord first
The window is a rolling 30 days from your first request, not a calendar month. On expiry the balance is topped back up to your cap automatically.

Check live any time - GET /v1/me is always free:

curl -H "X-API-Key: $MEALCP_API_KEY" "https://api.mealcp.com/v1/me"

{
  "name": "Beta tester",
  "email": "beta@example.com",
  "monthly_credit_cap": 1500,
  "credits_remaining": 842,
  "window_resets_at": "2026-09-19T14:00:21Z"
}

Error semantics

Status	Meaning	What to do
`401`	Missing, invalid, or revoked `X-API-Key`	Check the header; keys are shown once - rotate if lost
`402`	Credits exhausted for this window	Wait for `window_resets_at`, or request a higher cap
`429`	Rate limit exceeded	Honor the `Retry-After` header (seconds)
`422`	Invalid params	`error.details[]` names each problem

Rate limiting is per key, in a fixed per-minute window - bursts up to your per-minute limit pass, sustained traffic above it gets 429 with Retry-After. A rejected 429 never burns a credit.