Add clear message for 529 transient provider errors

[saarnilauri]

Add ProviderUnavailableException for transient provider errors

Relates to WordPress/ai-provider-for-anthropic#3

What

Adds a new ProviderUnavailableException to php-ai-client, following the same pattern as TokenLimitReachedException.

Why

When a provider returns a transient error (e.g. a 529 Overloaded, 500, 502, or 503), there was no dedicated exception to represent that state. The raw HTTP client error was surfaced directly, making it impossible for consumers to handle or retry cleanly.

Changes

• New: src/Common/Exception/ProviderUnavailableException.php — extends RuntimeException, stores the HTTP status code and API error type for downstream use
• Updated: tests/unit/Exceptions/ExceptionsTest.php — unit tests covering inheritance, default null values, and stored properties

Usage (by providers)

throw new ProviderUnavailableException(
    'Provider is temporarily unavailable.',
    $httpStatusCode,  // e.g. 529
    $errorType,       // e.g. "overloaded_error"
    $previous
);

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: saarnilauri <laurisaarni@git.wordpress.org>
Co-authored-by: felixarntz <flixos90@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.92%. Comparing base (30a1506) to head (9aee1c5).

Additional details and impacted files

@@             Coverage Diff              @@
##              trunk     #209      +/-   ##
============================================
+ Coverage     87.45%   87.92%   +0.46%     
  Complexity     1194     1194              
============================================
  Files            60       60              
  Lines          3858     3859       +1     
============================================
+ Hits           3374     3393      +19     
+ Misses          484      466      -18     

Flag	Coverage Δ
unit	87.92% <100.00%> (+0.46%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[felixarntz]

@saarnilauri I'm not sure why we need this, see WordPress/ai-provider-for-anthropic#3 (comment).

Let's discuss on that issue since that's the source of where this came from. Then we can act on this PR accordingly once we have identified the path forward.

[saarnilauri]

@felixarntz I rewrote the PR based on the discussin on WordPress/ai-provider-for-anthropic#3 (comment)

I added unit tests for the ServerException