infiniflow/ragflow · warning · ConnectorValidationError

Jira rate limit exceeded during validation (HTTP 429).

Error message

Jira rate limit exceeded during validation (HTTP 429).

What it means

ConnectorValidationError raised by _handle_validation_error when the Jira exception carries status_code == 429 - Atlassian rate limiting. Cloud enforces per-user and per-app request ceilings; the validation JQL search hit them and the server answered 429. Unlike auth errors, this is transient and resolves after the retry window.

Source

Thrown at common/data_source/jira/connector.py:287

                return (yield from self._load_from_checkpoint_internal(jql, checkpoint, start_filter=start))
            except Exception as exc:
                if attempt_start is not None and not retried_with_buffer and is_atlassian_date_error(exc):
                    attempt_start = attempt_start - ONE_HOUR
                    retried_with_buffer = True
                    logger.info(f"[Jira] Atlassian date error detected; retrying with start={attempt_start}.")
                    continue
                raise

    def _handle_validation_error(self, exc: Exception) -> None:
        status_code = getattr(exc, "status_code", None)
        if status_code == 401:
            raise InsufficientPermissionsError("Jira credential appears to be invalid or expired (HTTP 401).") from exc
        if status_code == 403:
            raise InsufficientPermissionsError("Jira token does not have permission to access the requested resources (HTTP 403).") from exc
        if status_code == 404:
            raise ConnectorValidationError("Jira resource not found (HTTP 404).") from exc
        if status_code == 429:
            raise ConnectorValidationError("Jira rate limit exceeded during validation (HTTP 429).") from exc

        message = getattr(exc, "text", str(exc))
        if not message:
            raise UnexpectedValidationError("Unexpected Jira validation error.") from exc

        raise ConnectorValidationError(f"Jira validation failed: {message}") from exc

    def _load_from_checkpoint_internal(
        self,
        jql: str,
        checkpoint: JiraCheckpoint,
        start_filter: SecondsSinceUnixEpoch | None = None,
    ) -> Generator[Document | ConnectorFailure, None, JiraCheckpoint]:
        assert self.jira_client, "load_credentials must be called before loading issues."

        page_size = self._full_page_size()
        new_checkpoint = copy.deepcopy(checkpoint)
        starting_offset = new_checkpoint.start_at or 0

View on GitHub (pinned to 554fb1133a)

Solutions

1. Retry after waiting - honor the Retry-After header on the chained response if present, else wait 30-60s with exponential backoff.
2. Reduce parallelism: one in-flight job per token; add jitter to schedules so jobs do not align.
3. Dedicate separate tokens or service accounts to high-volume jobs.
4. If sustained, check the Atlassian rate-limit dashboard for the account's ceiling.

Example fix

# before
for attempt in range(5):
    connector.validate_connector_settings()  # immediate retries -> 429 storm

# after
import time, random
for attempt in range(5):
    try:
        connector.validate_connector_settings()
        break
    except ConnectorValidationError as e:
        if '429' not in str(e) or attempt == 4:
            raise
        time.sleep(min(60, 2 ** attempt) + random.random())

def validate_with_backoff(connector, max_attempts: int = 5):
    for attempt in range(max_attempts):
        try:
            return connector.validate_connector_settings()
        except ConnectorValidationError as e:
            if 'HTTP 429' not in str(e) or attempt == max_attempts - 1:
                raise
            time.sleep(min(60, 2 ** attempt) + random.random())

When it happens

Trigger: Running validate_connector_settings() (which issues a JQL search) while the same token is used by other jobs, bulk syncs, or monitoring that saturate the rate budget; tight retry loops without backoff.

Common situations: Many connectors sharing one service account; backfill jobs issuing rapid JQL pages; CI validation suites hammering the API; Atlassian tightening limits for the plan tier.

Understand the failure class

• HTTP status errors: handling 4xx and 5xx responses — how to handle 4xx and 5xx responses properly.

Related errors

• Tenki rate limited, please retry: {exc}
• UCloud Agent Sandbox rate limited, please retry: {exc}
• API rate limit exceeded. ${limit} requests/hour for unauthen
• GitHub search returned no items.
• Too many concurrent browser fetch requests

AI-assisted analysis of infiniflow/ragflow@554fb1133a (2026-08-15). Data as JSON: /api/errors/4735967cd9fcf67f. Report an issue: GitHub.