# _errors

URL: /pounce/api/_errors/
Section: api
Description: Error hierarchy for pounce.

All pounce errors inherit from PounceError. Each error maps to an HTTP status
code for automatic error response generation.

Error categories:
- ParseError: malformed HTTP from the client (400)
- RequestTimeoutError: request or keep-alive timeout (408)
- LimitError: headers or body exceed configured limits (413/431)
- AppError: the ASGI application raised an exception (500)
- LifespanError: lifespan startup or shutdown failure (500)
- SupervisorError: worker spawn or crash-restart failure (500)
- WorkerError: worker-level failure reported to supervisor (500)
- TLSError: TLS configuration or handshake failure (500)
- ReloadError: file-watcher or worker-restart failure during reload (500)

Every error carries a semantic ``code`` of the form ``POUNCE_<CATEGORY>_<SPECIFIC>``
and an optional ``hint`` with actionable remediation. See
docs/design/error-codes.md for the naming scheme.

---

> For a complete page index, fetch /pounce/llms.txt.

Open LLM text
(/pounce/api/_errors/index.txt)

Share with AI

Ask Claude
(https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_errors%2Findex.txt)

Ask ChatGPT
(https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_errors%2Findex.txt)

Ask Gemini
(https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_errors%2Findex.txt)

Ask Copilot
(https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_errors%2Findex.txt)

Module

#
`_errors`

Error hierarchy for pounce.

All pounce errors inherit from PounceError. Each error maps to an HTTP status
code for automatic error response generation.

Error categories:

- ParseError: malformed HTTP from the client (400)

- RequestTimeoutError: request or keep-alive timeout (408)

- LimitError: headers or body exceed configured limits (413/431)

- AppError: the ASGI application raised an exception (500)

- LifespanError: lifespan startup or shutdown failure (500)

- SupervisorError: worker spawn or crash-restart failure (500)

- WorkerError: worker-level failure reported to supervisor (500)

- TLSError: TLS configuration or handshake failure (500)

- ReloadError: file-watcher or worker-restart failure during reload (500)

Every error carries a semantic`code` of the form `POUNCE_<CATEGORY>_<SPECIFIC>`
and an optional`hint`with actionable remediation. See
docs/design/error-codes.md for the naming scheme.

10Classes

## Classes

`PounceError`

4

▼

Base exception for all pounce server errors.

Bases:

`Exception`

Base exception for all pounce server errors.

#### Attributes

Name
Type
Description

`status_code`

`int`

—

`default_code`

`str`

—

#### Methods

Internal Methods
2

▼

`__init__`

5

▼

`def __init__(self, message: str, *, status_code: int | None = None, code: str | None = None, hint: str | None = None, doc: str | None = None) -> None`

##### Parameters

Name
Type
Description

`message`
`—`

`status_code`
`—`

Default:`None`

`code`
`—`

Default:`None`

`hint`
`—`

Default:`None`

`doc`
`—`

Default:`None`

`__reduce__`

0

`tuple[object, ...]`

▼

`def __reduce__(self) -> tuple[object, ...]`

##### Returns

`tuple[object, ...]`

`ParseError`

2

▼

Malformed HTTP request — h11 could not parse the input.

Bases:

`PounceError (/pounce/api/_errors/#PounceError)`

Malformed HTTP request — h11 could not parse the input.

#### Attributes

Name
Type
Description

`status_code`

`int`

—

`default_code`

`str`

—

`RequestTimeoutError`

2

▼

Request or keep-alive timeout exceeded.

Named ``RequestTimeoutError`` to avoid shadowing the built…

Bases:

`PounceError (/pounce/api/_errors/#PounceError)`

Request or keep-alive timeout exceeded.

Named `RequestTimeoutError` (/pounce/api/_errors/#RequestTimeoutError) to avoid shadowing the builtin
`TimeoutError` (which is a subclass of `OSError`).

#### Attributes

Name
Type
Description

`status_code`

`int`

—

`default_code`

`str`

—

`LimitError`

2

▼

Request headers or body exceed configured size limits.

Default status is 413 (Content Too Large). …

Bases:

`PounceError (/pounce/api/_errors/#PounceError)`

Request headers or body exceed configured size limits.

Default status is 413 (Content Too Large). Pass`status_code=431`
for header-specific limits (Request Header Fields Too Large).

#### Attributes

Name
Type
Description

`status_code`

`int`

—

`default_code`

`str`

—

`AppError`

2

▼

The ASGI application raised an unhandled exception.

Bases:

`PounceError (/pounce/api/_errors/#PounceError)`

The ASGI application raised an unhandled exception.

#### Attributes

Name
Type
Description

`status_code`

`int`

—

`default_code`

`str`

—

`LifespanError`

2

▼

ASGI lifespan startup or shutdown failed.

Bases:

`PounceError (/pounce/api/_errors/#PounceError)`

ASGI lifespan startup or shutdown failed.

#### Attributes

Name
Type
Description

`status_code`

`int`

—

`default_code`

`str`

—

`SupervisorError`

2

▼

Worker spawn failure or crash-restart exhaustion.

Bases:

`PounceError (/pounce/api/_errors/#PounceError)`

Worker spawn failure or crash-restart exhaustion.

#### Attributes

Name
Type
Description

`status_code`

`int`

—

`default_code`

`str`

—

`WorkerError`

2

▼

Worker-level failure that bubbles to the supervisor.

Bases:

`PounceError (/pounce/api/_errors/#PounceError)`

Worker-level failure that bubbles to the supervisor.

#### Attributes

Name
Type
Description

`status_code`

`int`

—

`default_code`

`str`

—

`TLSError`

2

▼

TLS configuration or handshake failure.

Bases:

`PounceError (/pounce/api/_errors/#PounceError)`

TLS configuration or handshake failure.

#### Attributes

Name
Type
Description

`status_code`

`int`

—

`default_code`

`str`

—

`ReloadError`

2

▼

File-watcher or worker-restart failure during reload.

Bases:

`PounceError (/pounce/api/_errors/#PounceError)`

File-watcher or worker-restart failure during reload.

#### Attributes

Name
Type
Description

`status_code`

`int`

—

`default_code`

`str`

—