Python SDK — Error Handling
Python SDK — Error Handling
Python SDK — Error Handling
| Class | HTTP status | When raised |
|---|---|---|
OnePinError | n/a | Base class for all onepin exceptions |
OnePinConfigurationError | n/a (client-side) | Missing API key, invalid base URL, unreadable credentials file |
OnePinAPIError | any non-2xx | Base class for all HTTP failures; catch this to handle any API error |
OnePinAuthError | 401 / 403 | Bad or expired key (401), or valid key with insufficient scope (403) |
OnePinNotFoundError | 404 | Resource does not exist or is not visible to the caller |
OnePinValidationError | 422 | Request body failed server-side validation |
OnePinRateLimitError | 429 | Quota exceeded; inspect .retry_after for the suggested wait in seconds |
OnePinServerError | 5xx | Unexpected backend error |
All OnePinAPIError subclasses expose:
| Attribute | Type | Description |
|---|---|---|
status_code | int | HTTP status code |
error_code | str | Machine-readable code, e.g. NOT_FOUND, VALIDATION_ERROR |
message | str | Human-readable message |
details | list | Additional validation details (populated on 422 only) |
request_id | str | None | ULID for tracing; include this when filing a support request |
response_body | bytes | None | Raw response bytes for debugging |
1 from onepin import OnePinClient 2 from onepin.errors import ( 3 OnePinConfigurationError, 4 OnePinNotFoundError, 5 OnePinAuthError, 6 OnePinValidationError, 7 OnePinRateLimitError, 8 OnePinServerError, 9 OnePinAPIError, 10 ) 11 12 client = OnePinClient(api_key="op_live_...") 13 14 try: 15 wf = client.workflows.get("3fa85f64-5717-4562-b3fc-2c963f66afa6") 16 except OnePinNotFoundError: 17 print("Workflow not found") 18 except OnePinAuthError as e: 19 print(f"Auth failure ({e.status_code}): {e.message}") 20 except OnePinValidationError as e: 21 print(f"Bad request: {e.details}") 22 except OnePinRateLimitError as e: 23 print(f"Rate limited — retry after {e.retry_after}s") 24 except OnePinServerError as e: 25 print(f"Server error {e.status_code} — request_id={e.request_id}") 26 except OnePinAPIError as e: 27 print(f"API error {e.status_code} [{e.error_code}]: {e.message}")
OnePinConfigurationError is raised before any HTTP call is made:
1 from onepin import OnePinClient 2 from onepin.errors import OnePinConfigurationError 3 4 try: 5 client = OnePinClient() # no key supplied, no env var, no credentials file 6 except OnePinConfigurationError as e: 7 print(e) # "No API key provided ..."
The SDK does not retry automatically. For idempotent operations, retry on OnePinServerError or network errors with exponential backoff:
1 import time 2 from onepin.errors import OnePinServerError, OnePinRateLimitError 3 4 for attempt in range(3): 5 try: 6 wf = client.workflows.get(workflow_id) 7 break 8 except OnePinRateLimitError as e: 9 time.sleep(e.retry_after or 60) 10 except OnePinServerError: 11 if attempt == 2: 12 raise 13 time.sleep(2 ** attempt)