Errors

This guide explains what happens when something goes wrong while you work with the NutritionSignals API. Use status codes plus the error type and message to debug quickly before reaching out to support.

You can tell if a request succeeded by checking the HTTP status code on the response. If it didn’t, the API will return a structured error body you can use to understand what failed and why.

Before contacting support, double-check your API key, endpoint path, request headers, and request body. Most errors are caused by missing headers, invalid JSON, or invalid parameters.

Status codes

Here are the common categories of status codes returned by the NutritionSignals API:

Name
2xx
Description
Success — the request completed and the response body contains data.
Name
4xx
Description
Client error — something about the request is invalid (missing/invalid API key, invalid JSON, missing fields, invalid parameters, etc.).
Name
5xx
Description
Server error — something went wrong on our side. Retry the request. If this persists, contact support with your request ID (if provided).

Error response format

When a request is unsuccessful, the API returns a JSON error response. Use the type to categorize the issue and the message to fix it. Some responses may include a request_id for support/debugging.

NutritionSignals errors are designed to be actionable. Most issues fall into one of these buckets:

Name
invalid_request
Description
The request is malformed or missing required fields (for example, missing text in POST /v1/foods/resolve).
Name
auth_error
Description
The API key is missing, invalid, or does not have access to the requested resource.
Name
rate_limited
Description
Too many requests in a short window. Retry after a delay and consider backoff.
Name
api_error
Description
An internal error occurred. Retry the request; if it continues, contact support.

Error response

{
  "type": "invalid_request",
  "message": "Missing required field: text",
  "status_code": 422,
  "request_id": "req_123"
}

Common errors

400 — Bad Request

The request body is invalid (for example, malformed JSON).

Example 400 response

{
  "type": "invalid_request",
  "message": "Invalid JSON body",
  "status_code": 400
}