Guides

Error handling

Every error response, from any endpoint, follows the same shape, so you can switch on error.code reliably.

Error envelope

error response

{
  "error": {
    "code": "NOT_FOUND",
    "message": "No food found with ID 'abc-123'.",
    "statusCode": 404,
    "timestamp": "2026-05-15T10:30:00Z",
    "path": "/v1/foods/abc-123"
  }
}

Common error codes

These apply across every endpoint. Endpoint-specific codes (like NOT_FOUND on Food Detail or PARSE_EMPTY_INPUT on Parse) are documented on their own endpoint pages.

Status	Code	Common cause	Suggested fix
400	BAD_REQUEST	Request body is not valid JSON.	Check that the body is well-formed JSON before sending it.
401	UNAUTHORIZED	No `X-API-Key`header, or the key doesn't match any active key (including revoked keys).	Send a valid, active key in `X-API-Key`. See Authentication.
422	VALIDATION_ERROR	Request query or body failed schema validation. The `issues` array on the response names the exact field.	Fix the field(s) listed in `issues`. See the endpoint page for which fields can trigger this.
429	RATE_LIMITED	Too many requests in the current window.	Back off and retry after the window resets. See Rate limits.
429	CREDIT_LIMIT_REACHED	Monthly credit allowance is used up.	Wait for the next billing cycle, or upgrade your plan for more credits.
500	INTERNAL_ERROR	Unexpected server-side failure.	Retry with exponential backoff. Contact support if it persists.

Retries

Retry on 500 and 503 with exponential backoff. Do not retry on 4xx. The request will keep failing until you change it.