docs: Add failure handling guidance for agent payment flows

[diptendulkar]

Add comprehensive documentation on expected agent behavior when handling common real-world failure scenarios in payment flows.

Covers:

• Mandate expiration during multi-step flows
• Price drift beyond mandate constraints
• Payment decline / PSP rejection
• Partial cart rejection (out of stock)

Includes:

• Detection code examples
• Expected agent behavior tables
• Example failure response JSON
• Decision framework for mandate enforcement vs user re-prompting
• Recovery action reference
• Agent behavior summary matrix

References the FailureResponse types from ap2.types.errors.

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

Description

Summary

Adds comprehensive documentation on expected agent behavior when handling common real-world failure scenarios in payment flows.

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

What's Included

Failure Scenarios Covered

Mandate Expiration - Intent or cart expires during multi-step flow
Price Drift - Final price exceeds original quote or constraints
Payment Decline - PSP/issuer rejects the transaction
Partial Cart Rejection - Items become unavailable (out of stock, discontinued)

For Each Scenario

• Detection code examples (Python)
• Expected agent behavior tables
• Example failure response JSON
• User communication guidance (what to say / what NOT to say)

Additional Content

• Decision Framework: Flowchart for mandate enforcement vs. user re-prompting
• Recovery Action Reference: When to use each RecoveryAction
• Agent Behavior Matrix: Quick-reference summary table

Files Changed

docs/topics/failure-handling.md - New documentation
mkdocs.yml - Added to navigation and llmstxt plugin

Preview

After merge, the doc will be available at:
https://ap2-protocol.org/topics/failure-handling/

Related

• Depends on PR feat: Add standard failure response types for AP2 #131 (feat: Add standard failure response types) for ap2.types.errors imports
• Addresses [Feat]: Add examples and guidance for handling failure states and enforcing mandate constraints #44

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[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 introduces essential documentation to standardize how agents manage and recover from various failure states within payment processing workflows. It aims to improve robustness and user experience by providing clear guidelines and examples for handling common issues like expired mandates, price changes, payment rejections, and inventory discrepancies, all while upholding user consent and mandate integrity.

Highlights

• New Failure Handling Documentation: A comprehensive guide has been added for agents on how to detect, communicate, and recover from common failure scenarios in payment flows, ensuring adherence to user intent and mandate constraints.
• Covered Scenarios: The documentation specifically addresses mandate expiration, price drift beyond mandate constraints, payment declines/PSP rejections, and partial cart rejections (e.g., out of stock).
• Practical Guidance: Each scenario includes Python detection code examples, tables outlining expected agent behavior, example failure response JSON, and user communication guidance. It also features a decision framework for mandate enforcement vs. user re-prompting, a recovery action reference, and an agent behavior summary matrix.
• Standardized Error Handling: The new documentation emphasizes the use of ap2.types.errors.FailureResponse for consistent failure communication across the ecosystem, referencing types from a dependent PR.

🧠 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 adds comprehensive documentation for handling failure states in agent payment flows. The new failure-handling.md document is well-structured, clear, and covers important scenarios like mandate expiration, price drift, and payment declines. The inclusion of code examples, behavior tables, and summary matrices makes it a valuable resource for developers.

My review includes a few suggestions to improve the robustness of a Python code example and to enhance the visual presentation of the flowcharts using Mermaid diagrams, which is already configured in your mkdocs.yml.