Exceptions

Custom exceptions to catch various errors.

ApiKeyMissingError

Bases: OpenAQError

Raised when an API key is required but not provided.

This exception is raised when attempting to access endpoints that require authentication but no API key has been configured in the client.

Parameters:

Name	Type	Description	Default
message	str	Human readable string describing the missing API key requirement.	required

Example

try: client = OpenAQ() # No API key provided client.get_protected_resource() except ApiKeyMissingError as e: print(f"API key required: {e}")

BadRequestError

Bases: HTTPClientError

HTTP 400 - Bad Request.

Raised when the API returns a 400 status code, indicating that the request was malformed or contains invalid syntax.

Parameters:

Name	Type	Description	Default
message	str	Human readable string describing the bad request.	required

Attributes:

Name	Type	Description
status_code	int	HTTP status code (400).

Example

try: client.get_locations(invalid_param="bad_value") except BadRequestError as e: print(f"Bad request: {e}")

BadGatewayError

Bases: ServerError

HTTP 502 - Bad Gateway.

Raised when the API returns a 502 status code, indicating that the gateway or proxy received an invalid response from an upstream server.

Parameters:

Name	Type	Description	Default
message	str	Human readable string describing the bad gateway error.	required

Attributes:

Name	Type	Description
status_code	int	HTTP status code (502).

Example

try: client.get_measurements() except BadGatewayError as e: print(f"Bad gateway: {e}")

ForbiddenError

Bases: HTTPClientError

HTTP 403 - Forbidden.

Raised when the API returns a 403 status code, indicating that the client is authenticated but does not have permission to access the requested resource.

Parameters:

Name	Type	Description	Default
message	str	Human readable string describing why access was forbidden.	required

Attributes:

Name	Type	Description
status_code	int	HTTP status code (403).

Example

try: client.delete_resource(resource_id=123) except ForbiddenError as e: print(f"Access denied: {e}")

GatewayTimeoutError

Bases: ServerError

HTTP 504 - Gateway Timeout.

Raised when the API returns a 504 status code, indicating that the gateway or proxy timed out while waiting for a response from an upstream server.

Parameters:

Name	Type	Description	Default
message	str	Human readable string describing the gateway timeout.	required

Attributes:

Name	Type	Description
status_code	int	HTTP status code (504).

Example

try: client.get_measurements() except GatewayTimeoutError as e: print(f"Gateway timeout: {e}")

HTTPRateLimitError

Bases: HTTPClientError

HTTP 429 - Too Many Requests.

Raised when the API returns a 429 status code, indicating that the client has exceeded the server-side rate limits.

Parameters:

Name	Type	Description	Default
message	str	Human readable string describing the rate limit error.	required

Attributes:

Name	Type	Description
status_code	int	HTTP status code (429).

Example

try: for i in range(10000): client.get_locations() except HTTPRateLimitError as e: print(f"API rate limit exceeded: {e}")

NotAuthorizedError

Bases: HTTPClientError

HTTP 401 - Unauthorized.

Raised when the API returns a 401 status code, indicating that authentication is required or the provided credentials are invalid.

Parameters:

Name	Type	Description	Default
message	str	Human readable string describing the authorization failure.	required

Attributes:

Name	Type	Description
status_code	int	HTTP status code (401).

Example

try: client = OpenAQ(api_key="invalid_key") client.get_measurements() except NotAuthorizedError as e: print(f"Authentication failed: {e}")

NotFoundError

Bases: HTTPClientError

HTTP 404 - Not Found.

Raised when the API returns a 404 status code, indicating that the requested resource does not exist.

Parameters:

Name	Type	Description	Default
message	str	Human readable string describing which resource was not found.	required

Attributes:

Name	Type	Description
status_code	int	HTTP status code (404).

Example

try: client.get_location(location_id=999999) except NotFoundError as e: print(f"Resource not found: {e}")

TimeoutError

Bases: HTTPClientError

HTTP 408 - Request Timeout.

Raised when the API returns a 408 status code, indicating that the server timed out waiting for the request to complete.

Parameters:

Name	Type	Description	Default
message	str	Human readable string describing the timeout.	required

Attributes:

Name	Type	Description
status_code	int	HTTP status code (408).

Note

This is different from network-level timeouts, which may raise different exceptions depending on the HTTP client library used.

Example

try: client.get_measurements(date_from="2000-01-01", date_to="2024-12-31") except TimeoutError as e: print(f"Request timed out: {e}")

RateLimitError

Bases: OpenAQError

Raised when client-side rate limiting is triggered.

This exception is raised by the SDK's internal rate limiting mechanism before making a request that would exceed configured rate limits. This is separate from HTTPRateLimitError, which indicates server-side rate limiting.

Parameters:

Name	Type	Description	Default
message	str	Human readable string describing the rate limit that was exceeded.	required

Example

try: for i in range(1000): client.get_locations() except RateLimitError as e: print(f"Rate limit exceeded: {e}")

ServerError

Bases: APIError

HTTP 5xx - Server Error.

Base class for all HTTP 5xx server error responses. Raised when the API encounters an internal error or is unable to process the request due to server-side issues.

Parameters:

Name	Type	Description	Default
message	str	Human readable string describing the server error.	required

Attributes:

Name	Type	Description
status_code	int	HTTP status code (500 or specific 5xx code).

Example

try: client.get_locations() except ServerError as e: print(f"Server error: {e}")

ServiceUnavailableError

Bases: ServerError

HTTP 503 - Service Unavailable.

Raised when the API returns a 503 status code, indicating that the server is temporarily unable to handle the request, typically due to maintenance or overload.

Parameters:

Name	Type	Description	Default
message	str	Human readable string describing why the service is unavailable.	required

Attributes:

Name	Type	Description
status_code	int	HTTP status code (503).

Example

try: client.get_locations() except ServiceUnavailableError as e: print(f"Service unavailable, try again later: {e}")

ValidationError

Bases: HTTPClientError

HTTP 422 - Unprocessable Entity.

Raised when the API returns a 422 status code, indicating that the request was well-formed but contains semantic errors or invalid parameter combinations.

Parameters:

Name	Type	Description	Default
message	str	Human readable string describing the validation error.	required

Attributes:

Name	Type	Description
status_code	int	HTTP status code (422).

Example

try: client.get_measurements(date_from="2024-01-01", date_to="2023-01-01") except ValidationError as e: print(f"Validation error: {e}")