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 JSON body. Most errors are caused by missing headers, malformed 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, etc.).
Name
5xx
Description
Server error — something went wrong on our side. 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.

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 Food Resolution).
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

401 — Unauthorized

This usually means your Authorization header is missing or incorrect.

Required header

Authorization: Bearer YOUR_API_KEY

422 — Unprocessable Entity

Your JSON body is valid JSON, but missing required fields or has invalid types.

Example 422 response

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

429 — Rate limited

You’ve exceeded the current rate limit. Retry with exponential backoff.

Example 429 response

{
  "type": "rate_limited",
  "message": "Too many requests. Please retry after a short delay.",
  "status_code": 429
}

5xx — Server error

Something went wrong on our side. Retry the request. If it keeps happening, contact support with any request_id returned.

Example 5xx response

{
  "type": "api_error",
  "message": "An internal error occurred. Please retry.",
  "status_code": 500,
  "request_id": "req_456"
}

Debug checklist

Confirm you’re calling the correct endpoint (example: POST /v1/foods/resolve)
Confirm Content-Type: application/json
Confirm Authorization: Bearer ...
Confirm your JSON is valid and includes required fields
Log the full error body (type, message, and request_id if present)

If you contact support, include the endpoint, timestamp, and the request_id from the error response (if provided).