[CXP-204] improve rate limit and temporary error handling

[johnallers]

Summary

• Fix rate limit errors being misclassified as PermissionDenied instead of Unavailable, causing syncs to fail instead of retry
• Add proper handling for *github.RateLimitError and *github.AbuseRateLimitError error types using errors.As()
• Extract rate limit data (reset time, limit, remaining) and attach to gRPC status details for proper backoff
• Add handling for 503/502/504 temporary server errors as Unavailable (retryable)

Problem

When go-github blocks requests client-side due to rate limits, it returns a RateLimitError with a synthetic 403 response that has empty headers. The existing isRatelimited() check failed because it expects X-Ratelimit-Remaining header to equal "0", but the synthetic response has no headers. This caused rate limit errors to be misclassified as PermissionDenied, which is not retried by the SDK.

Solution

Check for go-github error types before checking HTTP status codes:

1. *github.RateLimitError → extract Rate.Reset, Rate.Limit, Rate.Remaining → codes.Unavailable with rate limit details
2. *github.AbuseRateLimitError → use RetryAfter duration → codes.Unavailable with rate limit details
3. 503/502/504 responses → codes.Unavailable (retryable)

The SDK's retry logic now receives proper rate limit data to calculate appropriate backoff times.

Test plan

• Build passes
• Tests pass
• Lint passes
• Test with a GitHub org that hits rate limits in service mode

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Improved detection and messaging for rate limit errors, including clearer retry timing and guidance.
  • Better handling of temporary service outages (502/503/504), with clearer "service unavailable" behavior for affected requests.
  • Wrapped rate-limit details into error responses so users receive more actionable retry information.

[linear]

CXP-204 Improve baton-github connector rate limit handling

[coderabbitai]

Walkthrough

Adds rate-limit detection and wrapping utilities to connector helpers: functions to derive rate-limit details from GitHub errors and Retry-After, expanded wrapGitHubError to attach RateLimitDescription to gRPC errors, and a helper to classify temporary service-unavailable responses (502/503/504).

Changes

Cohort / File(s)	Summary
Rate-limit & error-wrapping helpers pkg/connector/helpers.go	Added rateLimitDescriptionFromRate and rateLimitDescriptionFromRetryAfter, wrapErrorWithRateLimitDetails, isTemporarilyUnavailable; enhanced wrapGitHubError to detect RateLimitError and AbuseRateLimitError, attach rate-limit details to gRPC status, preserve existing rate-limit checks and temporary-server handling.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant Connector
  participant GitHubAPI
  participant gRPCStatus

  Client->>Connector: API request
  Connector->>GitHubAPI: Call GitHub
  alt RateLimitError
    GitHubAPI-->>Connector: RateLimitError (with Rate)
    Connector->>Connector: rateLimitDescriptionFromRate()
    Connector->>gRPCStatus: attach RateLimitDescription
    gRPCStatus-->>Connector: gRPC error with details
    Connector-->>Client: gRPC rate-limited error
  else AbuseRateLimitError
    GitHubAPI-->>Connector: AbuseRateLimitError (with Retry-After)
    Connector->>Connector: rateLimitDescriptionFromRetryAfter()
    Connector->>gRPCStatus: attach RateLimitDescription
    gRPCStatus-->>Connector: gRPC error with details
    Connector-->>Client: gRPC rate-limited error
  else TemporaryServerError (502/503/504)
    GitHubAPI-->>Connector: 502/503/504
    Connector->>Connector: isTemporarilyUnavailable()
    Connector-->>Client: treated as unavailable error
  else OtherError
    GitHubAPI-->>Connector: Other error
    Connector->>Connector: existing auth/permission checks
    Connector-->>Client: wrapped error
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 I nibble logs in moonlit code,
I stitch rate-limits on the road,
Retry-after crumbs I weave,
So gRPC errors gently leave —
Hoppity, wrapped and neatly showed. 🥕

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 71.43% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title accurately describes the main change: improving rate limit and temporary error handling as detailed in the objectives.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch jallers/cxp-204

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}