Errors

<!-- order: 4 | Every error says what went wrong and what to change. The codes, and what to do about each. -->

Errors are problem details (RFC 9457), with Content-Type: application/problem+json:

{
  "type": "https://api.foodintegrityproject.org/docs/guides/errors#insufficient_scope",
  "title": "The token doesn't have the scope this needs",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the verification.read scope.",
  "request_id": "6f1c…"
}

Use code in your code: it never changes. detail is for people. Quote request_id when you ask for help: it finds the call in the request log.

The codes

invalid_request

400. A parameter is missing or wrong; field names it. Fix the request and send it again.

unauthorized

401. No token, or it has expired or been revoked. Get a new token (sign in, or POST /v2/oauth/token) and try again.

insufficient_scope

403. The token is valid but lacks the scope this needs (required_scope). Ask for a key with that scope.

wrong_environment

403. A sandbox key on /v2, or a production key on /sandbox/v2. Use the other address, or a key for this one.

not_found

404. No such record, or not one your token may see.

no_such_endpoint

404. Check the path against the reference.

method_not_allowed

405. The path exists, but not with this method.

rate_limited

429. Too many requests in a minute. Wait retry_after seconds (also in RateLimit-Reset), then carry on. See Status and limits.

server_error

500. Something went wrong on our side. Try again in a minute; if it keeps happening, send the request_id.