feat: Add reactive token refresh on 401/403 API responses

[devin-ai-integration]

Summary

When an API returns a 401 or 403 error indicating an expired token, the connector should automatically refresh the token and retry the request. Currently, the CDK only performs proactive token refresh (checking expiry before requests) but does not handle reactive refresh when the API itself rejects the token.

Problem

A user reported a 403 error from the Amazon Selling Partner connector:

'GET' request to 'https://sellingpartnerapi-na.amazon.com/reports/2021-06-30/reports/521059020455' 
failed with status code '403' and error message: 'Access to requested resource is denied.'. 
Response: {'errors': [{'code': 'Unauthorized', 'message': 'Access to requested resource is denied.', 
'details': 'The access token you provided has expired.'}]}

The connector has OAuth configured and the CDK's AbstractOauth2Authenticator.get_access_token() method does check token_has_expired() before each request. However, when the API returns a 403 "token expired" error (rather than the proactive check catching it), the connector fails immediately.

Root Cause Analysis

1. Current behavior: The CDK's default_error_mapping.py treats both 401 and 403 as ResponseAction.FAIL:

   401: ErrorResolution(
       response_action=ResponseAction.FAIL,
       failure_type=FailureType.config_error,
       error_message="HTTP Status Code: 401. Error: Unauthorized...",
   ),
   403: ErrorResolution(
       response_action=ResponseAction.FAIL,
       failure_type=FailureType.config_error,
       error_message="HTTP Status Code: 403. Error: Forbidden...",
   ),

2. Existing retry logic: The CDK (v0.30.0) added retry logic for token refresh requests on 429, 500, 502, 504 errors. However, this is for the token refresh endpoint, not for API calls that return auth errors.

3. Why this happens:

   • Amazon LWA access tokens are valid for ~1 hour
   • Long-running syncs can exceed this duration
   • Clock skew between Airbyte and the API can cause early expiration
   • The proactive check relies on tracking expiry time internally, which may not match the API's actual token validity

Proposed Solution

Add reactive token refresh capability that:

1. Detects auth-related errors (401, or 403 with specific error messages like "token expired")
2. Attempts to refresh the access token
3. Retries the failed request with the new token
4. Falls back to failure if refresh fails or retry still fails

This could be implemented as:

• A configurable option in the authenticator to specify which status codes/error patterns should trigger refresh
• Integration with the existing ErrorHandler to intercept auth errors before failing
• A retry decorator or middleware in the HTTP client

Affected Components

• airbyte_cdk/sources/streams/http/error_handlers/default_error_mapping.py
• airbyte_cdk/sources/streams/http/requests_native_auth/abstract_oauth.py
• airbyte_cdk/sources/streams/http/http_client.py
• Declarative framework's HttpRequester and error handling

Related

• CDK v0.30.0 added "OAuth: retry refresh access token requests" for transient errors on the token endpoint
• This issue is about retrying API calls when they return auth errors

Context

• Devin session: https://app.devin.ai/sessions/e49a02f10e9940fabfaee7782dc938e6
• Reported by: teo@airbyte.io
• Affected connector: source-amazon-seller-partner (but applies to all OAuth connectors)