fix(core): treat retryable errors with >5 min delay as terminal quota errors

[gsquared94]

Summary

Treat retryable quota errors with retry delays exceeding 5 minutes as terminal quota errors. When the server suggests waiting longer than 5 minutes, the user is effectively locked out, so we should trigger the fallback/credits flow instead of silently waiting.

Details

Added a MAX_RETRYABLE_DELAY_SECONDS = 300 (5 minutes) threshold constant in classifyGoogleError. Three code paths that create RetryableQuotaError with a delay are now checked against this threshold:

1. Fallback "Please retry in" regex path — parses retry delay from error message text
2. Cloud Code RATE_LIMIT_EXCEEDED path — uses RetryInfo delay or default 10s
3. RetryInfo path — uses the structured retry delay from the API response

If the delay exceeds 300 seconds, a TerminalQuotaError is returned instead, which triggers the existing fallback/credits flow.

The PerMinute quota paths (hardcoded 60s) and no-delay paths are unaffected.

How to Validate

1. Run the unit tests:

   npm test -w @google/gemini-cli-core -- src/utils/googleQuotaErrors.test.ts

2. Verify the new/updated tests:
   • should return TerminalQuotaError for retry delays over 5 minutes (301s → terminal)
   • should return RetryableQuotaError when retry delay is exactly 5 minutes (300s → retryable)
   • should return TerminalQuotaError for Cloud Code RATE_LIMIT_EXCEEDED with retry delay over 5 minutes (600s → terminal)
   • should return TerminalQuotaError when fallback "Please retry in" delay exceeds 5 minutes (400s → terminal)

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[sehoon38]

LGTM

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the error handling mechanism by reclassifying quota errors with excessively long retry delays as terminal errors. Previously, the system might silently wait for a retry period exceeding 5 minutes, effectively locking out the user. By treating these as terminal errors, the system will now immediately trigger a fallback or credits flow, providing a more responsive and user-friendly experience when faced with prolonged service unavailability due to quota exhaustion.

Highlights

• New Retry Delay Threshold: Introduced a MAX_RETRYABLE_DELAY_SECONDS constant set to 5 minutes (300 seconds) to define the maximum acceptable delay for a retryable quota error.
• Terminal Quota Error Classification: Modified the classifyGoogleError function to reclassify RetryableQuotaError instances as TerminalQuotaError if the suggested retry delay exceeds the new 5-minute threshold.
• Expanded Error Handling Coverage: Applied this new logic to three specific error handling paths: parsing "Please retry in" messages, Cloud Code RATE_LIMIT_EXCEEDED errors, and structured RetryInfo delays.

Changelog

• packages/core/src/utils/googleQuotaErrors.test.ts
  • Updated an existing test case to expect TerminalQuotaError for delays over 5 minutes.
  • Added a new test case for Cloud Code RATE_LIMIT_EXCEEDED with a retry delay over 5 minutes.
  • Added a new test case for fallback "Please retry in" messages with delays over 5 minutes.
  • Added a new test case to confirm RetryableQuotaError for delays exactly 5 minutes.
• packages/core/src/utils/googleQuotaErrors.ts
  • Introduced MAX_RETRYABLE_DELAY_SECONDS constant set to 300 seconds (5 minutes).
  • Modified the logic for parsing "Please retry in" messages to check retryDelaySeconds against MAX_RETRYABLE_DELAY_SECONDS.
  • Modified the Cloud Code RATE_LIMIT_EXCEEDED handling to check effectiveDelay against MAX_RETRYABLE_DELAY_SECONDS.
  • Modified the RetryInfo handling to check delaySeconds against MAX_RETRYABLE_DELAY_SECONDS.

Activity

• No human activity has been recorded for this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request modifies the Google API error classification logic to treat retryable quota errors with a delay greater than 5 minutes as terminal errors. A constant, MAX_RETRYABLE_DELAY_SECONDS, is introduced and used to check the delay in three separate code paths within classifyGoogleError. The changes are logical and correctly implemented. The unit tests have been updated and expanded to cover the new behavior, including a boundary case for a 5-minute delay. The implementation is sound.