Errors | OnePin

Exception hierarchy

Class	HTTP status	When raised
`ApiError`	any non-2xx	Base class for all HTTP failures; catch this to handle any API error
`NotFoundError`	404	Resource does not exist or is not visible to the caller
`ConflictError`	409	Request conflicts with the current state of a resource
`UnprocessableEntityError`	422	Request body failed server-side validation

Import paths:

1 from onepin.core.api_error import ApiError
2 from onepin.errors import NotFoundError, ConflictError, UnprocessableEntityError

All error classes expose:

Attribute	Type	Description
`status_code`	`int \| None`	HTTP status code
`headers`	`dict \| None`	Response headers
`body`	`Any`	Parsed response body

Catching errors

1 import os
2 from onepin import OnePinClient
3 from onepin.core.api_error import ApiError
4 from onepin.errors import NotFoundError, ConflictError, UnprocessableEntityError
5 
6 client = OnePinClient(token=os.environ["ONEPIN_API_KEY"])
7 
8 try:
9     result = client.workflows.get(workflow_id="3fa85f64-5717-4562-b3fc-2c963f66afa6")
10     wf = result.data
11 except NotFoundError:
12     print("Workflow not found")
13 except ConflictError as e:
14     print(f"Conflict ({e.status_code}): {e.body}")
15 except UnprocessableEntityError as e:
16     print(f"Validation error: {e.body}")
17 except ApiError as e:
18     print(f"API error {e.status_code}: {e.body}")

Retrying

The SDK does not retry automatically. For idempotent operations, retry on 5xx errors or network failures with exponential backoff. Check e.status_code to distinguish server errors from client errors, and inspect e.headers for a Retry-After value on rate-limit responses:

1 import time
2 from onepin.core.api_error import ApiError
3 
4 for attempt in range(3):
5     try:
6         result = client.workflows.get(workflow_id=workflow_id)
7         wf = result.data
8         break
9     except ApiError as e:
10         if e.status_code is not None and e.status_code >= 500:
11             if attempt == 2:
12                 raise
13             # Honour Retry-After header if present, otherwise use backoff
14             ra_header = (e.headers or {}).get("Retry-After")
15             wait = float(ra_header) if ra_header else 2 ** attempt
16             time.sleep(wait)
17         else:
18             raise  # 4xx errors are not retryable