fix(billing-cost-management-mcp-server): map each service's bad-token code to invalid_next_token (#4861)

* fix(billing-cost-management-mcp-server): map each service's bad-token code to invalid_next_token

Only Cost Explorer, Budgets and the Price List API report a rejected
pagination token as InvalidNextTokenException. The other paged services
use a generic code: ValidationException (Billing views, billing
preferences, credits, enterprise support, Invoicing, Billing Conductor,
Cost Optimization Hub, Free Tier, Savings Plans, Pricing Calculator) or
InvalidParameterValueException (Compute Optimizer Automation). A bogus or
expired next_token on those tools came back as the generic code with the
"correct your arguments" hint instead of invalid_next_token and the
"restart without next_token" hint.

Each of those operations' PageSpec now names its service's code in
caller_token_error_codes, the mechanism Compute Optimizer and the Billing
Group cost report already use. The code is read as a rejected token only
when the caller sent next_token, on the first request; elsewhere it stays
the service's own error.

* fix(billing-cost-management-mcp-server): require a generic bad-token code to name the token

A generic code such as ValidationException also reports other invalid
arguments. With a caller next_token, a service can still reject another
argument first (ListBillingViews checks arns before the token), and the
helper reported that as invalid_next_token. A caller_token_error_codes
code now counts as a rejected token only when the error message names
the token. GetBillingGroupCostReport keeps code-only matching, because
its expired-token InternalServerException need not name the token.

Author: finklen-amazon

src/billing-cost-management-mcp-server/awslabs/billing_cost_management_mcp_server/tools/bcm_pricing_calculator_tools.py

@@ -49,6 +49,8 @@
     token_key_in_response='nextToken',
     page_max=25,
     page_size_param='maxResults',
+    # The service reports a bad caller next_token as ValidationException.
+    caller_token_error_codes=frozenset({'ValidationException'}),
 )
 # ListWorkloadEstimateUsage returns up to 300 usage lines per page.
 LIST_WORKLOAD_ESTIMATE_USAGE_PAGE_SPEC = PageSpec(
@@ -57,6 +59,8 @@
     token_key_in_response='nextToken',
     page_max=300,
     page_size_param='maxResults',
+    # The service reports a bad caller next_token as ValidationException.
+    caller_token_error_codes=frozenset({'ValidationException'}),
 )
 PREFERENCES_NOT_CONFIGURED_ERROR = 'BCM Pricing Calculator preferences are not configured. Please configure preferences before using this service.'
 

src/billing-cost-management-mcp-server/awslabs/billing_cost_management_mcp_server/tools/billing_conductor_operations.py

@@ -55,6 +55,8 @@ def _bc_page_spec(result_key: str) -> PageSpec:
         token_key_in_response='NextToken',
         page_max=100,
         page_size_param='MaxResults',
+        # Billing Conductor reports a bad caller next_token as ValidationException.
+        caller_token_error_codes=frozenset({'ValidationException'}),
     )
 
 
@@ -188,6 +190,8 @@ def _format_billing_groups(billing_groups: List[Dict[str, Any]]) -> List[Dict[st
     token_param='NextToken',
     token_key_in_response='NextToken',
     page_max=100,
+    # The service reports a bad caller next_token as ValidationException.
+    caller_token_error_codes=frozenset({'ValidationException'}),
 )
 
 
@@ -315,7 +319,8 @@ async def list_billing_group_cost_reports(
 # A changed parameter or a malformed token fails with ValidationException, and an expired token
 # can fail with ValidationException or InternalServerException. Either code on a call that
 # carried a next_token means that token is unusable, so the helper maps it to
-# invalid_next_token only then.
+# invalid_next_token only then. The expired-token InternalServerException need not name the
+# token, so this spec does not require the message to.
 BC_GET_BILLING_GROUP_COST_REPORT = PageSpec(
     result_key='BillingGroupCostReportResults',
     token_param='NextToken',
@@ -324,6 +329,7 @@ async def list_billing_group_cost_reports(
     page_size_param='MaxResults',
     page_min=200,
     caller_token_error_codes=frozenset({'ValidationException', 'InternalServerException'}),
+    caller_token_message_required=False,
 )
 
 

src/billing-cost-management-mcp-server/awslabs/billing_cost_management_mcp_server/tools/billing_preferences_operations.py

@@ -54,6 +54,8 @@ def _create_billing_client() -> Any:
     token_key_in_response='nextToken',
     page_max=50,
     page_size_param='maxResults',
+    # The service reports a bad caller next_token as ValidationException.
+    caller_token_error_codes=frozenset({'ValidationException'}),
 )
 
 

src/billing-cost-management-mcp-server/awslabs/billing_cost_management_mcp_server/tools/bvs_operations.py

@@ -94,6 +94,8 @@ async def get_billing_view(
     token_key_in_response='nextToken',
     page_max=100,
     page_size_param='maxResults',
+    # The service reports a bad caller next_token as ValidationException.
+    caller_token_error_codes=frozenset({'ValidationException'}),
 )
 
 
@@ -144,6 +146,8 @@ async def list_source_views_for_billing_view(
     token_key_in_response='nextToken',
     page_max=100,
     page_size_param='maxResults',
+    # The service reports a bad caller next_token as ValidationException.
+    caller_token_error_codes=frozenset({'ValidationException'}),
 )
 
 
@@ -295,6 +299,8 @@ async def get_resource_policy(
     token_key_in_response='nextToken',
     page_max=100,
     page_size_param='maxResults',
+    # The service reports a bad caller next_token as ValidationException.
+    caller_token_error_codes=frozenset({'ValidationException'}),
 )
 
 

src/billing-cost-management-mcp-server/awslabs/billing_cost_management_mcp_server/tools/compute_optimizer_automation_operations.py

@@ -381,55 +381,71 @@ async def get_enrollment_configuration(
     token_key_in_response='nextToken',
     page_max=100,
     page_size_param='maxResults',
+    # The service reports a bad caller next_token as InvalidParameterValueException.
+    caller_token_error_codes=frozenset({'InvalidParameterValueException'}),
 )
 COA_LIST_AUTOMATION_EVENT_STEPS = PageSpec(
     result_key='automationEventSteps',
     token_param='nextToken',
     token_key_in_response='nextToken',
     page_max=100,
     page_size_param='maxResults',
+    # The service reports a bad caller next_token as InvalidParameterValueException.
+    caller_token_error_codes=frozenset({'InvalidParameterValueException'}),
 )
 COA_LIST_AUTOMATION_EVENT_SUMMARIES = PageSpec(
     result_key='automationEventSummaries',
     token_param='nextToken',
     token_key_in_response='nextToken',
     page_max=100,
     page_size_param='maxResults',
+    # The service reports a bad caller next_token as InvalidParameterValueException.
+    caller_token_error_codes=frozenset({'InvalidParameterValueException'}),
 )
 COA_LIST_AUTOMATION_RULES = PageSpec(
     result_key='automationRules',
     token_param='nextToken',
     token_key_in_response='nextToken',
     page_max=100,
     page_size_param='maxResults',
+    # The service reports a bad caller next_token as InvalidParameterValueException.
+    caller_token_error_codes=frozenset({'InvalidParameterValueException'}),
 )
 COA_LIST_RECOMMENDED_ACTIONS = PageSpec(
     result_key='recommendedActions',
     token_param='nextToken',
     token_key_in_response='nextToken',
     page_max=100,
     page_size_param='maxResults',
+    # The service reports a bad caller next_token as InvalidParameterValueException.
+    caller_token_error_codes=frozenset({'InvalidParameterValueException'}),
 )
 COA_LIST_RECOMMENDED_ACTION_SUMMARIES = PageSpec(
     result_key='recommendedActionSummaries',
     token_param='nextToken',
     token_key_in_response='nextToken',
     page_max=100,
     page_size_param='maxResults',
+    # The service reports a bad caller next_token as InvalidParameterValueException.
+    caller_token_error_codes=frozenset({'InvalidParameterValueException'}),
 )
 COA_LIST_AUTOMATION_RULE_PREVIEW = PageSpec(
     result_key='previewResults',
     token_param='nextToken',
     token_key_in_response='nextToken',
     page_max=100,
     page_size_param='maxResults',
+    # The service reports a bad caller next_token as InvalidParameterValueException.
+    caller_token_error_codes=frozenset({'InvalidParameterValueException'}),
 )
 COA_LIST_AUTOMATION_RULE_PREVIEW_SUMMARIES = PageSpec(
     result_key='previewResultSummaries',
     token_param='nextToken',
     token_key_in_response='nextToken',
     page_max=100,
     page_size_param='maxResults',
+    # The service reports a bad caller next_token as InvalidParameterValueException.
+    caller_token_error_codes=frozenset({'InvalidParameterValueException'}),
 )
 
 

src/billing-cost-management-mcp-server/awslabs/billing_cost_management_mcp_server/tools/cost_optimization_hub_helpers.py

@@ -54,20 +54,26 @@
     token_key_in_response='nextToken',
     page_max=1000,
     page_size_param='maxResults',
+    # The service reports a bad caller next_token as ValidationException.
+    caller_token_error_codes=frozenset({'ValidationException'}),
 )
 COH_LIST_RECOMMENDATION_SUMMARIES = PageSpec(
     result_key='items',
     token_param='nextToken',
     token_key_in_response='nextToken',
     page_max=1000,
     page_size_param='maxResults',
+    # The service reports a bad caller next_token as ValidationException.
+    caller_token_error_codes=frozenset({'ValidationException'}),
 )
 COH_LIST_EFFICIENCY_METRICS = PageSpec(
     result_key='efficiencyMetricsByGroup',
     token_param='nextToken',
     token_key_in_response='nextToken',
     page_max=1000,
     page_size_param='maxResults',
+    # The service reports a bad caller next_token as ValidationException.
+    caller_token_error_codes=frozenset({'ValidationException'}),
 )
 # Performance ranking's internal fetch: EFFICIENCY_PARETO_PAGE_SIZE groups per page, highest
 # spend first, up to EFFICIENCY_PARETO_MAX_PAGES pages (a cap of pages x page size groups).

src/billing-cost-management-mcp-server/awslabs/billing_cost_management_mcp_server/tools/credits_operations.py

@@ -64,6 +64,8 @@
     token_key_in_response='nextToken',
     page_max=500,
     page_size_param='maxResults',
+    # The service reports a bad caller next_token as ValidationException.
+    caller_token_error_codes=frozenset({'ValidationException'}),
 )
 
 # IAM action required by each operation, used to build an actionable message

src/billing-cost-management-mcp-server/awslabs/billing_cost_management_mcp_server/tools/enterprise_support_operations.py

@@ -56,6 +56,8 @@
     token_key_in_response='nextToken',
     page_max=100,
     page_size_param='maxResults',
+    # The service reports a bad caller next_token as ValidationException.
+    caller_token_error_codes=frozenset({'ValidationException'}),
 )
 
 

src/billing-cost-management-mcp-server/awslabs/billing_cost_management_mcp_server/tools/free_tier_usage_tools.py

@@ -37,6 +37,8 @@
     token_key_in_response='nextToken',
     page_max=1000,
     page_size_param='maxResults',
+    # The service reports a bad caller next_token as ValidationException.
+    caller_token_error_codes=frozenset({'ValidationException'}),
 )
 
 free_tier_usage_server = FastMCP(

src/billing-cost-management-mcp-server/awslabs/billing_cost_management_mcp_server/tools/invoice_units_operations.py

@@ -43,6 +43,8 @@
     token_key_in_response='NextToken',
     page_max=500,
     page_size_param='MaxResults',
+    # The service reports a bad caller next_token as ValidationException.
+    caller_token_error_codes=frozenset({'ValidationException'}),
 )