Add support for retry_with_header parameter to fix timestamp overflow error

[n1ghter]

Problem

When Jira Server or Confluence Server returns HTTP 429 (Rate Limiting) with a Retry-After header containing a large value, the atlassian-python-api library throws an OverflowError: timestamp too large to convert to C _PyTime_t error.

This affects both Jira and Confluence integrations in mcp-atlassian.

This is a known issue in atlassian-python-api. Related issues:

• #1499 - OverflowError: timestamp too large to convert to C _PyTime_t response.headers["Retry-After"] (Jira)
• #1593 - "Retry-After" header too large (Confluence) - same error when Confluence returns HTTP 429

Current Behavior

The error occurs in atlassian/rest_client.py:304 when trying to process the Retry-After header:

time.sleep(int(response.headers["Retry-After"]))
OverflowError: timestamp too large to convert to C _PyTime_t

Stack trace:

File "/app/.venv/lib/python3.10/site-packages/atlassian/rest_client.py", line 304, in _handle
    time.sleep(int(response.headers["Retry-After"]))
OverflowError: timestamp too large to convert to C _PyTime_t

Proposed Solution

According to issue #1499 in atlassian-python-api, the solution is to set retry_with_header=False when creating the Jira object. Currently, mcp-atlassian doesn't support this parameter.

In /app/.venv/lib/python3.10/site-packages/mcp_atlassian/jira/client.py, the Jira object is created without this parameter:

self.jira = Jira(
    url=self.config.url,
    token=self.config.personal_token,
    cloud=self.config.is_cloud,
    verify_ssl=self.config.ssl_verify,
    # retry_with_header is not passed - defaults to True
)

Request

Please add support for retry_with_header parameter for both Jira and Confluence:

1. Add environment variable support (e.g., JIRA_RETRY_WITH_HEADER and CONFLUENCE_RETRY_WITH_HEADER)
2. Pass retry_with_header=False (or from config/env) to both Jira and Confluence constructors
3. This will prevent the overflow error when Jira Server or Confluence Server returns HTTP 429 with large Retry-After values

Example Implementation

# In jira/client.py
retry_with_header = os.getenv("JIRA_RETRY_WITH_HEADER", "true").lower() == "true"

self.jira = Jira(
    url=self.config.url,
    token=self.config.personal_token,
    cloud=self.config.is_cloud,
    verify_ssl=self.config.ssl_verify,
    retry_with_header=retry_with_header,  # Add this parameter
)

# Similarly for Confluence in confluence/client.py
confluence_retry_with_header = os.getenv("CONFLUENCE_RETRY_WITH_HEADER", "true").lower() == "true"

self.confluence = Confluence(
    url=self.config.url,
    token=self.config.personal_token,
    cloud=self.config.is_cloud,
    verify_ssl=self.config.ssl_verify,
    retry_with_header=confluence_retry_with_header,  # Add this parameter
)

Environment

• Jira Server: 10.7.4 (Server/Data Center)
• mcp-atlassian: latest (November 4, 2025)
• atlassian-python-api: 3.41.19+
• Python: 3.10.19

Related Issues

atlassian-python-api

• #1499 - OverflowError: timestamp too large to convert to C _PyTime_t response.headers["Retry-After"] (Jira - opened Jan 27, 2025)
• #1593 - "Retry-After" header too large (Confluence - opened Oct 8, 2025) - same OverflowError: timestamp too large to convert to C _PyTime_t error

Similar Issues

The error occurs when time.sleep() receives a value that exceeds the maximum value for C _PyTime_t. This is a known limitation when processing HTTP 429 responses with large Retry-After header values from Jira Server/Data Center.

Root Cause:

• Jira Server/Data Center may return very large values in the Retry-After header (potentially Unix timestamps instead of seconds)
• Python's time.sleep() has limitations on the maximum value it can accept (platform-dependent, typically related to C _PyTime_t)
• The atlassian-python-api library attempts to use int(response.headers["Retry-After"]) directly without validation

Impact:

• Affects all users of mcp-atlassian with Jira Server/Data Center and Confluence Server/Data Center
• Error occurs even with very rare requests (not a rate limiting issue per se)
• Prevents proper handling of HTTP 429 responses for both Jira and Confluence
• Issue atlassian-python-api "Retry-After" header too large #1593 shows this affects Confluence users as well (opened Oct 8, 2025)

Additional Notes

• The error occurs even with very rare requests (not a rate limiting issue)
• The variables JIRA_RETRY_WITH_HEADER=false and CONFLUENCE_RETRY_WITH_HEADER=false are already being passed to the container, but mcp-atlassian doesn't use them
• This would be a simple fix that would resolve the issue for many users

Thank you for considering this feature request!