For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
  • Get Started
    • Introduction
    • Quickstart
    • Authentication
  • Python SDK
    • Install
    • Usage
    • Errors
  • CLI
    • Overview
LogoLogo
On this page
  • Exception hierarchy
  • Catching errors
  • Configuration errors
  • Retrying
Python SDK

Python SDK — Error Handling

Was this page helpful?
Previous

Overview

Next
Built with

Exception hierarchy

ClassHTTP statusWhen raised
OnePinErrorn/aBase class for all onepin exceptions
OnePinConfigurationErrorn/a (client-side)Missing API key, invalid base URL, unreadable credentials file
OnePinAPIErrorany non-2xxBase class for all HTTP failures; catch this to handle any API error
OnePinAuthError401 / 403Bad or expired key (401), or valid key with insufficient scope (403)
OnePinNotFoundError404Resource does not exist or is not visible to the caller
OnePinValidationError422Request body failed server-side validation
OnePinRateLimitError429Quota exceeded; inspect .retry_after for the suggested wait in seconds
OnePinServerError5xxUnexpected backend error

All OnePinAPIError subclasses expose:

AttributeTypeDescription
status_codeintHTTP status code
error_codestrMachine-readable code, e.g. NOT_FOUND, VALIDATION_ERROR
messagestrHuman-readable message
detailslistAdditional validation details (populated on 422 only)
request_idstr | NoneULID for tracing; include this when filing a support request
response_bodybytes | NoneRaw response bytes for debugging

Catching errors

1from onepin import OnePinClient
2from onepin.errors import (
3 OnePinConfigurationError,
4 OnePinNotFoundError,
5 OnePinAuthError,
6 OnePinValidationError,
7 OnePinRateLimitError,
8 OnePinServerError,
9 OnePinAPIError,
10)
11
12client = OnePinClient(api_key="op_live_...")
13
14try:
15 wf = client.workflows.get("3fa85f64-5717-4562-b3fc-2c963f66afa6")
16except OnePinNotFoundError:
17 print("Workflow not found")
18except OnePinAuthError as e:
19 print(f"Auth failure ({e.status_code}): {e.message}")
20except OnePinValidationError as e:
21 print(f"Bad request: {e.details}")
22except OnePinRateLimitError as e:
23 print(f"Rate limited — retry after {e.retry_after}s")
24except OnePinServerError as e:
25 print(f"Server error {e.status_code} — request_id={e.request_id}")
26except OnePinAPIError as e:
27 print(f"API error {e.status_code} [{e.error_code}]: {e.message}")

Configuration errors

OnePinConfigurationError is raised before any HTTP call is made:

1from onepin import OnePinClient
2from onepin.errors import OnePinConfigurationError
3
4try:
5 client = OnePinClient() # no key supplied, no env var, no credentials file
6except OnePinConfigurationError as e:
7 print(e) # "No API key provided ..."

Retrying

The SDK does not retry automatically. For idempotent operations, retry on OnePinServerError or network errors with exponential backoff:

1import time
2from onepin.errors import OnePinServerError, OnePinRateLimitError
3
4for 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)