Exceptions

The top-level imports below are jira2py's custom low-level HTTP, transport, and attachment-protocol error hierarchy. JiraError is not a catch-all for every exception a jira2py call can raise; high-level helper errors are independent. See Helper errors for that hierarchy.

All low-level exceptions are importable from the top-level package:

from jira2py import (
    JiraError,
    JiraAuthenticationError,
    JiraConnectionError,
    JiraAPIError,
    JiraNotFoundError,
    JiraRateLimitError,
    JiraValidationError,
)

For usage patterns and examples, see Error Handling.

Low-level hierarchy

JiraError
├── JiraConnectionError
└── JiraAPIError
    ├── JiraAuthenticationError
    ├── JiraNotFoundError
    ├── JiraRateLimitError
    └── JiraValidationError

JiraError

Base exception for jira2py's custom low-level HTTP, transport, and attachment-protocol errors. It does not cover independent helper errors, built-in validation failures, or helper model-validation errors.

Attribute	Type	Description
message	str	Human-readable error description
response	Response \| None	The raw HTTP response, when available; sanitized attachment and managed-media paths expose no response object

JiraAuthenticationError

Raised when authentication or authorization fails (HTTP 401, 403).

Inherits from JiraAPIError, so it is also caught by except JiraAPIError and carries the same status_code, response, and error_messages metadata when available. For direct construction, status_code defaults to 401 and response defaults to None.

JiraConnectionError

Raised on network-level failures: timeouts, DNS resolution errors, connection refused.

Inherits all attributes from JiraError.

JiraAPIError

Raised for HTTP 4xx and 5xx responses not covered by a more specific exception.

Attribute	Type	Description
status_code	int	HTTP status code
error_messages	list[str]	Error messages extracted from the Jira response body

Includes JiraAuthenticationError and all other HTTP-error subclasses.

Also inherits message and response from JiraError. response may be None when no HTTP response object is available.

JiraNotFoundError

Raised when a requested resource is not found (HTTP 404).

Inherits all attributes from JiraAPIError.

JiraRateLimitError

Raised when the API rate limit is exceeded (HTTP 429) and all retries have been exhausted.

Attribute	Type	Description
retry_after	float \| None	Seconds the server asked to wait
rate_limit_reason	str \| None	Which limit was hit (e.g., jira-burst-based, jira-quota-tenant-based)
reset_at	str \| None	Timestamp when the rate limit window resets

Also inherits all attributes from JiraAPIError.

See Rate Limiting for how automatic retries work before this exception is raised.

JiraValidationError

Raised when request validation fails (HTTP 400). Typically indicates malformed input or missing required fields.

Inherits all attributes from JiraAPIError.