Error Handling

Every error response follows a consistent format with an AI-friendly .suggestion field.

Error format

{
  "error": {
    "code": "search/query_required",
    "message": "Missing required parameter: q",
    "suggestion": "Add a search query: /v1/search?q=chicken breast",
    "docs": "https://chowapi.dev/docs/search"
  }
}

Field	Description
`code`	Machine-readable error code (category/specific)
`message`	Human-readable error description
`suggestion`	Actionable fix, designed for AI assistants to read and act on
`docs`	Link to relevant documentation page

Why .suggestion?

AI assistants (Claude, ChatGPT, etc.) read error responses to decide what to do next. The .suggestion field tells them exactly how to fix the issue. No guessing, no hallucinating fixes. This makes ChowAPI the most AI-debuggable food API available.

Error codes

Authentication

Code	Status	Description
`auth/missing_key`	401	No ticket, no meal. Add an Authorization header.
`auth/invalid_key`	401	That key doesn't unlock anything. Check your API key.

Rate Limiting

Code	Status	Description
`rate_limit/burst_exceeded`	429	Slow down — you're eating too fast. Wait 60 seconds.
`rate_limit/daily_exceeded`	429	Daily call limit reached. Resets at midnight UTC.

Search

Code	Status	Description
`search/query_required`	400	The kitchen needs an order. Pass a `q` parameter.
`search/query_too_short`	400	That's not enough to work with. Give us at least 2 characters.
`search/offset_too_large`	400	You've gone too deep in the pantry. Max offset is 200.

Barcode & Foods

Code	Status	Description
`barcode/invalid`	400	That doesn't look like a barcode. We need 8-14 digits.
`barcode/not_found`	404	That barcode isn't in our kitchen. Yet.
`foods/invalid_id`	400	That's not a valid food ID. UUIDs only.
`food/not_found`	404	That food doesn't exist in our database. Yet.
`billing/payment_required`	402	The tab is empty. Grab credits at chowapi.dev/pricing.
`server/internal`	500	Something's burning in the kitchen. We're on it.