[Platform] Implement RateLimitExceededException handling across AI platforms

[floranpagliai]

Q	A
Bug fix?	no
New feature?	no
Docs?	no
Issues	#528
License	MIT

• Created a RateLimitExceededException to handle 429 across all AI platforms
• Unified the handling of rate limit responses with platform-specific retry information
• Used platform-specific header extraction for each provider:
  • Anthropic: Standard retry-after HTTP header (seconds)
  • Gemini: No retry information provided
  • OpenAI: Custom headers x-ratelimit-reset-requests and x-ratelimit-reset-tokens

[VincentLanglet]

Could be nice to document ResultConverterInterface::convert that it can throws exception then.

With something like

    /**
     * @param array<string, mixed> $options
     *
     * @throws RateExceededException when rate limit exceeeded
     * @throws RuntimeException when another error occured
     */
    public function convert(RawResultInterface $result, array $options = []): ResultInterface;

[OskarStark]

lets call it RateLimitExceededException

[floranpagliai]

@OskarStark installation of PHPStan is flakky, don't know if you can launch again the CI.

[floranpagliai]

Could be nice to document ResultConverterInterface::convert that it can throws exception then.

With something like

    /**
     * @param array<string, mixed> $options
     *
     * @throws RateExceededException when rate limit exceeeded
     * @throws RuntimeException when another error occured
     */
    public function convert(RawResultInterface $result, array $options = []): ResultInterface;

Agreed, will include it in a try to have a higher level ResultConverter.

[chr-hertel]

don't see this as a RuntimeException tho

Suggested change

	final class RateLimitExceededException extends \RuntimeException implements ExceptionInterface
	final class RateLimitExceededException extends \InvalidArgumentException implements ExceptionInterface

[floranpagliai]

I get your point, but I’m not sure \InvalidArgumentException is the best fit here. A rate limit being exceeded isn’t really about invalid input, it’s more of an external condition depending of usage. That’s why I went with \RuntimeException.

Another option could be to extend directly from a generic \Exception or define a dedicated base exception for API-related errors ?

[VincentLanglet]

Maybe my point of view, but i consider

• a LogicException being an exception which should never happen unless bad code is written, and the dev should fix his code. (Bad param, bad call, case which shouldn't exist, etc)
• a RuntimeException being an exception which is not avoidable and might occurs under some circonstances

Here, it seems to be a Runtime one to me.

[VincentLanglet]

But what about extending directly the symfony/ai RuntimeException
https://github.com/symfony/ai/blob/main/src/platform/src/Exception/RuntimeException.php

rather than extending \RuntimeException and implementing the ExceptionInterface ?

[floranpagliai]

Went with directly extending https://github.com/symfony/ai/blob/main/src/platform/src/Exception/RuntimeException.php

[chr-hertel]

Thank you @floranpagliai.