Errors and pagination
Non-2xx responses raise a typed exception; list operations return a lazy pagination wrapper.
Errors
All exceptions descend from ForgejoError. APIError carries status_code, body, and the raw httpx.Response; transport failures raise TransportError, and responses that do not match the Spec raise DecodeError.
ForgejoError
Base class for every error raised by pyfj.
APIError
The instance returned a non-2xx response.
Attributes:
| Name | Type | Description |
|---|---|---|
status_code |
the HTTP status code. |
|
body |
the JSON-decoded body when possible, otherwise the response text. |
|
response |
the raw :class: |
body
body = _parse_body(response)
response
response = response
status_code
status_code = response.status_code
TransportError
The request produced no HTTP response: connection failure or timeout.
Wraps the underlying :class:httpx.TransportError (available as
:attr:cause, and chained via raise ... from).
cause
cause = cause
method
method = method
url
url = url
DecodeError
A documented response could not be decoded to its declared type.
Raised by :func:pyfj._runtime.decode.decode when the body is not valid
JSON for the requested model, fails pydantic validation, or does not have
the documented JSON shape.
reason
reason = reason
response
response = response
BadRequestError
HTTP 400: the request was malformed.
UnauthorizedError
HTTP 401: credentials are missing or invalid.
ForbiddenError
HTTP 403: the authenticated user may not perform the operation.
NotFoundError
HTTP 404: the requested object does not exist.
MethodNotAllowedError
HTTP 405: the operation is not allowed on this resource.
ConflictError
HTTP 409: the request conflicts with the current state.
PreconditionFailedError
HTTP 412: a precondition (ETag, If-Match, ...) failed.
PayloadTooLargeError
HTTP 413: the uploaded payload exceeds a server limit.
UnprocessableEntityError
HTTP 422: the request was well-formed but semantically invalid.
LockedError
HTTP 423: the resource is locked.
ServerError
HTTP 5xx: the instance failed to process a valid request.
Pagination
List operations return Paginated[T] (sync) or AsyncPaginated[T] (async): iterating walks pages transparently, .total_count mirrors X-Total-Count, and .page(n) fetches a single page.
Paginated
Transparent multi-page iterator for sync list operations.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fetch_page
|
Callable[[int], Page[T]]
|
callback fetching the 1-based page number it is given. |
required |
first_page
|
Page[T]
|
the page fetched by the client hook before construction. |
required |
start_page
|
int
|
1-based number of |
1
|
total_count
total_count: int | None
Total number of items reported by the instance, if it reported one.
page
page(number: int) -> list[T]
Fetch one 1-based page explicitly.
Raises:
| Type | Description |
|---|---|
ValueError
|
|
AsyncPaginated
Transparent multi-page async iterator for async list operations.
Mirrors :class:Paginated; page must be awaited and iteration uses
async for.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fetch_page
|
Callable[[int], Awaitable[Page[T]]]
|
async callback fetching the 1-based page number it is given. |
required |
first_page
|
Page[T]
|
the page fetched by the client hook before construction. |
required |
start_page
|
int
|
1-based number of |
1
|
total_count
total_count: int | None
Total number of items reported by the instance, if it reported one.
page
page(number: int) -> list[T]
Fetch one 1-based page explicitly.
Raises:
| Type | Description |
|---|---|
ValueError
|
|