Exceptions API

The exceptions module provides custom exceptions for the USDA FDC client.

FdcApiError

class usda_fdc.exceptions.FdcApiError(message, status_code=None)[source]

Base exception for all FDC API errors.

Parameters:

message (str) – A description of what went wrong.
status_code (int | None) – The HTTP status the API replied with, when there was a reply at all. It is None for failures that never reached the API — a refused connection, a timeout, an unreadable body.

class usda_fdc.exceptions.FdcAuthError(message, status_code=None)[source]

Exception raised when authentication fails.

api.data.gov, which fronts FDC, answers an invalid or missing key with 403 rather than 401, so both statuses raise this.

Parameters:

class usda_fdc.exceptions.FdcRateLimitError(message, status_code=None)[source]

Exception raised when the API rate limit is exceeded.

Parameters:

class usda_fdc.exceptions.FdcTimeoutError(message, status_code=None)[source]

Exception raised when a request to the FDC API times out.

Distinct from a generic FdcApiError so callers can tell “slow” from “broken” — a timeout is usually worth retrying, a 400 is not.

Parameters:

class usda_fdc.exceptions.FdcValidationError(message, status_code=None)[source]

Exception raised when the API rejects the request as invalid (HTTP 400).

Typically a parameter outside the range FDC accepts, such as a page_size above 200.

Parameters:

class usda_fdc.exceptions.FdcResourceNotFoundError(message, status_code=None)[source]

Exception raised when a requested resource is not found (HTTP 404).

A food that does not exist is an ordinary outcome of a lookup, not a breakdown, so callers deserve to catch it on its own.

Parameters: