judgevet.domain.errors

Status: draft.

`judgevet.domain.errors`

Domain error types for Jev System One API.

Examples:

from judgevet.domain.errors import (
    JevAuthError,
    JevError,
    JevRequestError,
    JevResponseError,
    JevServiceError,
)

try:
    # Your API call here
    pass
except JevAuthError as exc:
    # Handle authentication errors
    if exc.retryable:
        # Retry with backoff
        pass
except JevRequestError as exc:
    # Handle client request errors (do not retry)
    pass
except JevServiceError as exc:
    # Handle service errors
    if exc.retryable:
        # Retry with backoff
        pass
except JevError as exc:
    # Handle all other Jev errors
    pass

Name	Type	Description
`JevError`	`type`	Base exception for all Jev errors.
`JevAuthError`	`type`	401/403 authentication errors.
`JevRequestError`	`type`	4xx client request errors.
`JevResponseError`	`type`	2xx with unparseable body.
`JevServiceError`	`type`	5xx or transport errors.

`JevAuthError`

Bases: JevError

Authentication error - 401 or 403.

Raised when the API key is missing, invalid, or lacks the necessary permissions to access the requested resource.

Attributes:

Name	Type	Description
`args`	`tuple`	Standard exception arguments containing the message.
`status_code`	`int`	Always 401 or 403.

Examples:

error = JevAuthError("Unauthorized", 401)
assert error.retryable is False

`retryable` `property`

Return True if the error is retryable.

Returns:

Type	Description
`bool`	False for auth errors (401, 403).

`init(message, status_code)`

Initialize the auth error.

Parameters:

Name	Type	Description	Default
`message`	`str`	The error message.	required
`status_code`	`int`	The HTTP status code (401 or 403).	required

Raises:

Type	Description
`ValueError`	If status_code is not 401 or 403.

`JevError`

Bases: Exception

Base exception for all Jev-related errors.

This is the parent of the service-error hierarchy, not local policy errors or every HTTPX exception. Redirects can propagate raw HTTPX status errors. The base class always reports retryable=False; subclasses override it.

Attributes:

Name	Type	Description
`args`	`tuple`	Standard exception arguments containing the message.
`status_code`	`int \| None`	The HTTP status code if available, None otherwise.
`retryable`	`bool`	Advisory retry classification; False on this base class.

Examples:

error = JevError("Something went wrong", 500)
assert error.retryable is False

`retryable` `property`

Return True if the error is retryable.

Returns:

Type	Description
`bool`	False on this base class, independent of status_code.

`init(message, status_code=None)`

Initialize the error.

Parameters:

Name	Type	Description	Default
`message`	`str`	The error message.	required
`status_code`	`int \| None`	The HTTP status code if available.	`None`

Examples:

error = JevError("Something went wrong", 500)
assert error.retryable is False

`str()`

Return string representation.

`JevRateLimitError`

Bases: JevError

Rate limit exceeded - 429.

Raised when the API returns a 429 status code indicating the client has exceeded the rate limit. The caller chooses retry limits; the adapter defaults to one attempt.

See: https://docs.typesafe.ai/api.md

Attributes:

Name	Type	Description
`args`	`tuple`	Standard exception arguments containing the message.
`status_code`	`int`	Always 429.

Examples:

error = JevRateLimitError("Rate limit exceeded", 429)
assert error.retryable is True

`retryable` `property`

Return True if the error is retryable.

Returns:

Type	Description
`bool`	True for rate limit errors (429).

`init(message, status_code)`

Initialize the rate limit error.

Parameters:

Name	Type	Description	Default
`message`	`str`	The error message.	required
`status_code`	`int`	The HTTP status code (must be 429).	required

Raises:

Type	Description
`ValueError`	If status_code is not 429.

`JevRequestError`

Bases: JevError

Client request error - 4xx (except 401/403).

Raised when the API rejects the request due to invalid parameters, malformed input, or other client-side issues.

Attributes:

Name	Type	Description
`args`	`tuple`	Standard exception arguments containing the message.
`status_code`	`int`	The HTTP status code (4xx).

Examples:

error = JevRequestError("Bad Request", 400)
assert error.retryable is False

`retryable` `property`

Return True if the error is retryable.

Returns:

Type	Description
`bool`	False for request errors (4xx).

`init(message, status_code)`

Initialize the request error.

Parameters:

Name	Type	Description	Default
`message`	`str`	The error message.	required
`status_code`	`int`	The HTTP status code (4xx).	required

Raises:

Type	Description
`ValueError`	If status_code is not a 4xx code or is 401/403.

`JevResponseError`

Bases: JevError

Response parsing error - 2xx with invalid body.

Raised when the API returns a 2xx status code but the response body cannot be parsed into the expected domain types. This is a local parsing failure. Live calls verify only the fields they exercised; other fields remain inferred from documentation.

Attributes:

Name	Type	Description
`args`	`tuple`	Standard exception arguments containing the message.
`status_code`	`int`	Always 2xx.

Examples:

error = JevResponseError("Parse error", 200)
assert error.retryable is False

`retryable` `property`

Return True if the error is retryable.

Returns:

Type	Description
`bool`	False for response errors (2xx with invalid body).

`init(message, status_code)`

Initialize the response error.

Parameters:

Name	Type	Description	Default
`message`	`str`	The error message.	required
`status_code`	`int`	The HTTP status code (2xx).	required

Raises:

Type	Description
`ValueError`	If status_code is not a 2xx code.

`JevServiceError`

Bases: JevError

Server service error - 5xx or transport failures.

Raised when the API returns a 5xx status code or when a transport error occurs (network issues, timeouts, etc.).

Attributes:

Name	Type	Description
`args`	`tuple`	Standard exception arguments containing the message.
`status_code`	`int \| None`	The HTTP status code (5xx) or None for transport errors.

Examples:

error = JevServiceError("Internal Server Error", 500)
assert error.retryable is True

`retryable` `property`

Return True if the error is retryable.

Returns:

Type	Description
`bool`	True for service errors (5xx) and transport failures (status None).

`init(message, status_code=None)`

Initialize the service error.

Parameters:

Name	Type	Description	Default
`message`	`str`	The error message.	required
`status_code`	`int \| None`	The HTTP status code (5xx) or None for transport errors.	`None`

Raises:

Type	Description
`ValueError`	If status_code is not a 5xx code when provided.

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

judgevet.domain.errors