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	1
GET /v1/products/{product_id}	yes	1
GET /v1/prices/{product_id}	yes	1
GET /v1/prices/{product_id}/observations	yes	1
GET /v1/me	yes	0
GET /v1/coverage	no	0
GET /v1/categories	no	0
GET /v1/tags	no	0
GET /health, GET /openapi.json	no	0

Query parameters don’t change the cost - a paginated page_size=100 search costs the same 1 credit as page_size=1.

Your allowance

• Free key: 200 credits / 30 days, 5 req/min per IP
• Beta key: 10,000 credits / 30 days, 300 req/min - request one
• 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": 10000,
  "credits_remaining": 8421,
  "window_resets_at": "2026-09-19T14:00:21Z"
}

Error semantics

Status	Meaning	What to do
401	Missing/invalid 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 a fixed per-minute window - bursts up to your per-minute limit pass, sustained traffic above it gets 429 with Retry-After.