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 Authorization header
`auth/invalid_key`	401	Key format invalid or key revoked

Rate Limiting

Code	Status	Description
`rate_limit/burst_exceeded`	429	Per-minute request limit exceeded
`rate_limit/monthly_exceeded`	429	Monthly call quota exceeded

Search

Code	Status	Description
`search/query_required`	400	Missing q parameter
`search/query_too_short`	400	Query < 2 characters
`search/offset_too_large`	400	Offset > 500

Barcode & Foods

Code	Status	Description
`barcode/invalid`	400	Invalid barcode format
`barcode/not_found`	404	Barcode not in database
`foods/invalid_id`	400	Not a valid UUID
`food/not_found`	404	Food ID not found