feat: Add standard failure response types for AP2

[diptendulkar]

Add error types to define a consistent structure for communicating failure states between agents. This enables predictable error handling and recovery flows for common real-world failure scenarios.

New types:

• FailureCategory: Categories of failures (MANDATE_EXPIRED, PRICE_DRIFT, PAYMENT_DECLINED, CART_MODIFIED, MERCHANT_REJECTION, etc.)
• RecoveryAction: Recommended recovery actions (RETRY_ALLOWED, USER_CONFIRMATION_REQUIRED, NEW_MANDATE_REQUIRED, etc.)
• PaymentDeclineCode: Common PSP/issuer decline codes
• ItemRejectionReason: Reasons for cart item rejection
• RejectedItem: Details about rejected items
• FailureResponse: Standard failure response structure

Addresses issue #44 : Add examples and guidance for handling failure states

Description

Problem

Currently, AP2 lacks a standardized way to communicate failure states between agents. This makes it difficult for agents to:

• Detect and categorize failures consistently
• Determine appropriate recovery actions
• Communicate failures to users in a predictable way

Solution

Added a new errors.py module with standard types for failure communication:

Usage Example

from ap2.types.errors import FailureResponse, FailureCategory, RecoveryAction

failure = FailureResponse(
    category=FailureCategory.PRICE_DRIFT,
    message="Final price exceeds original quote by 15%",
    recovery_action=RecoveryAction.USER_CONFIRMATION_REQUIRED,
    original_value={"amount": 100.00, "currency": "USD"},
    actual_value={"amount": 115.00, "currency": "USD"},
    details={"drift_percent": 15.0}
)

Files Changed

• src/ap2/types/errors.py - New file with error types
• src/ap2/types/__init__.py - Export new types

Fixes #44 🦕

[gemini-code-assist]

Summary of Changes

Hello @diptendulkar, 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 establishes a foundational framework for robust error management within the AP2 ecosystem. By defining clear, standardized types for various failure states and their corresponding recovery actions, it aims to significantly enhance the reliability and predictability of agent interactions, ensuring a more consistent experience when encountering issues.

Highlights

• Standardized Failure Types: Introduced a comprehensive set of standard failure response types for the Agent Payments Protocol (AP2) to ensure consistent communication of failure states between agents.
• New Enums for Failure Categorization: Added FailureCategory (e.g., MANDATE_EXPIRED, PRICE_DRIFT, PAYMENT_DECLINED), RecoveryAction (e.g., USER_CONFIRMATION_REQUIRED, RETRY_ALLOWED), PaymentDeclineCode, and ItemRejectionReason to classify various failure scenarios and recommended actions.
• Structured Failure Response Model: Created a FailureResponse Pydantic model that encapsulates all relevant details of a failure, including category, message, recovery action, and optional contextual data like RejectedItem details or decline_code.
• Improved Error Handling: The new types enable predictable error handling and recovery flows, addressing common real-world failure scenarios and making it easier for agents to detect, categorize, and communicate failures consistently.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

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 introduces a comprehensive set of standardized failure response types for AP2, which is a great step towards predictable error handling. The new types in src/ap2/types/errors.py are well-defined and documented. My review includes a suggestion to simplify the FailureResponse model by removing a couple of redundant fields to improve API clarity, and a minor style suggestion to improve code readability. Overall, this is a valuable addition.