> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://onepin.ai/docs/guides/handle-errors/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://onepin.ai/_mcp/server.

# Handle errors

#### Python

Every non-2xx response raises a typed exception. Catch `ApiError` to handle any of them, or a subclass for a specific status:

```python
from onepin import OnepinClient
from onepin.core.api_error import ApiError
from onepin.errors import NotFoundError, ConflictError, UnprocessableEntityError

client = OnepinClient()

try:
    wf = client.workflows.get(workflow_id="…").data
except NotFoundError:
    print("not found")
except UnprocessableEntityError as e:
    print("invalid request:", e.body)
except ApiError as e:
    print(f"API error {e.status_code}: {e.body}")
```

| Class                      | HTTP                                     |
| -------------------------- | ---------------------------------------- |
| `BadRequestError`          | 400                                      |
| `ForbiddenError`           | 403 (missing scope or model not on plan) |
| `NotFoundError`            | 404                                      |
| `ConflictError`            | 409                                      |
| `UnprocessableEntityError` | 422                                      |

`401` (bad key) and `429` (rate limited) arrive as plain `ApiError` — branch on `e.status_code`. The SDK doesn't auto-retry; for `429`, honor the `Retry-After` header before retrying.

A `422` body carries a list of detail entries. Beyond `field` and `message`, an entry about your script content can also carry `line_numbers` (which script lines the problem is on) and `min_chars` (the minimum length that would have been accepted) — enough to point a user at the offending line instead of rejecting the whole request opaquely.

#### CLI

Errors print to stderr (as a JSON envelope in `--json` mode); successful data goes to stdout. Branch on the exit code:

| Code  | Meaning                                           |
| ----- | ------------------------------------------------- |
| `0`   | Success                                           |
| `1`   | Runtime error — auth, network, server, validation |
| `2`   | Usage error — unknown flag or bad value           |
| `130` | Interrupted (`Ctrl+C`)                            |

```bash
if ! onepin workflows run "$WF" --watch; then
  echo "run failed" >&2
fi
```

> Onepin is a voice workflow platform that orchestrates, validates, and ships production-ready audio across 33 TTS models.