Skip to content

Exceptions

oilpriceapi.exceptions

Typed OilPriceAPI errors and compatibility parsing for API responses.

OilPriceAPIError

Bases: Exception

Stable base contract for API, transport, and configuration errors.

BadRequestError

Bases: OilPriceAPIError

Raised for malformed requests (HTTP 400).

AuthenticationError

Bases: OilPriceAPIError

Raised when API authentication fails (HTTP 401).

PaymentRequiredError

Bases: OilPriceAPIError

Raised when account billing or plan access is required (HTTP 402).

PermissionDeniedError

Bases: OilPriceAPIError

Raised when the account lacks permission for a feature (HTTP 403).

RateLimitError

Bases: OilPriceAPIError

Raised when API rate limit is exceeded (HTTP 429).

seconds_until_reset property

Calculate seconds until rate limit resets.

DataNotFoundError

Bases: OilPriceAPIError

Raised when requested data is not found (HTTP 404).

ValidationError

Bases: OilPriceAPIError

Raised when request validation fails (HTTP 422).

FuturesContractError

Bases: ValidationError, ValueError

Raised when a futures contract or slug cannot be resolved (#122).

Two base classes, deliberately:

  • ValidationError -- so except OilPriceAPIError catches it. Every documented recovery path in this SDK is written against that base class, and #111 turned 18 live catalog codes from "resolved to a DIFFERENT instrument" into "raises". A refusal is only recoverable if it is catchable, and a bare builtin ValueError was not.
  • ValueError -- so code written against the pre-#111 raise ValueError keeps working. This is not a breaking change.

SubscriptionIntervalError

Bases: ValidationError, ValueError

Raised locally when a subscription interval cannot be parsed (#100).

Two base classes, deliberately:

  • ValidationError -- so except OilPriceAPIError catches it, like every other refusal in this SDK. It is raised before any request is built, so status_code is None, field is "interval" and value is the rejected input.
  • ValueError -- so code written against the pre-#100 raise ValueError from subscriptions.create(interval=...) and normalize_interval keeps working. This is not a breaking change.

Only the interval path that already raised ValueError gets the dual base. Refusals introduced with get/update/pause/resume and the delete id check raise a plain ValidationError.

ServerError

Bases: OilPriceAPIError

Raised when the server returns HTTP 5xx.

NetworkError

Bases: OilPriceAPIError

Raised when a request cannot reach or complete with the API.

TimeoutError

Bases: NetworkError

Raised when a request times out.

ConfigurationError

Bases: OilPriceAPIError

Raised when client configuration is invalid.

error_from_response(response, *, commodity=None)

Normalize canonical, legacy, and malformed HTTP error responses.

error_from_exception(error, *, api_key=None, timeout=None)

Normalize transport failures while redacting the configured API key.