feat!: granular counterparty payout failure reasons by JasonCWang · Pull Request #689 · lightsparkdev/grid-api

JasonCWang · 2026-07-14T21:53:17Z

Summary

Reworks OutgoingTransactionFailureReason so every value is an outcome an integrator acts on, and syncs the docs to match.

Added — granular payout failures, set at the payout-partner boundary:

PAYOUT_RETURNED — receiving bank accepted then returned/reversed the payout
LIMIT_EXCEEDED — payout exceeds a recipient-, account-, or corridor-level limit
ACCOUNT_CANNOT_RECEIVE — account exists but can't accept the payment (dormant/frozen/restricted/unsupported currency)
ACCOUNT_INVALID — recipient account not found or details wrong
COMPLIANCE_REJECTED — rejected on compliance grounds (sanctions/watchlist/KYC-AML)

Removed — the four values #629 added. Each names an internal step of how a payment is processed rather than something an integrator handles differently:

EXECUTION_FAILED_POST_DEBIT and SETTLEMENT_FAILED say where on the way to settlement the failure happened. Both collapse into QUOTE_EXECUTION_FAILED, whose description now covers that whole path and states that a debited amount is refunded automatically.
TIMEOUT and MANUAL_REFUND describe operator-initiated refunds. That outcome already surfaces on the refund object, whose reason enum carries TIMEOUT and USER_CANCELLATION.

LSP_OPERATIONAL_FAILURE was on this branch earlier and is removed for the same reason: an operational failure on the provider side reaches integrators as QUOTE_EXECUTION_FAILED, the same outcome to act on.

Deprecated in the description, still returned: LIGHTNING_PAYMENT_FAILED (superseded by QUOTE_EXECUTION_FAILED) and COUNTERPARTY_POST_TX_FAILED (coarse fallback for historical rows). SCA_NOT_COMPLETED (#762) is untouched — a customer letting an SCA challenge expire is a distinct, actionable outcome.

Final enum: QUOTE_EXPIRED, QUOTE_EXECUTION_FAILED, FUNDING_AMOUNT_MISMATCH, SCA_NOT_COMPLETED, PAYOUT_RETURNED, LIMIT_EXCEEDED, ACCOUNT_CANNOT_RECEIVE, ACCOUNT_INVALID, COMPLIANCE_REJECTED, LIGHTNING_PAYMENT_FAILED, COUNTERPARTY_POST_TX_FAILED.

Breaking change

Removing four values is flagged by oasdiff as request-property-enum-value-removed (ERR), because failureReason also appears in the webhook:outgoing-payment and webhook:agent-action bodies. The PR carries the breaking-change label and needs API-reviewer approval.

The server-side mapping for the removed values has to be updated before clients are regenerated, or failureReason renders empty — the regression #629 was fixing.

Changes

OpenAPI (OutgoingTransactionFailureReason.yaml + bundle): the enum above, with per-value descriptions and deprecation notes.
Docs: synced the failure-reasons table in transaction-lifecycle.mdx and the list in the error-handling.mdx snippet to the enum — dropped the non-existent INSUFFICIENT_BALANCE, reordered to enum order, and fixed a FAILED webhook example to use ACCOUNT_INVALID.

Rebased onto main, which added #629's values and #762's SCA_NOT_COMPLETED.

Test plan

make build — bundles cleanly; clean rebuild produces no diff
make lint-openapi — 0 errors (redocly + spectral)

vercel · 2026-07-14T21:53:23Z

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ignored	Preview	Aug 13, 2026 6:02pm
grid-wallet-demo	Ignored	Preview	Aug 13, 2026 6:02pm

mintlify · 2026-07-14T21:55:12Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Grid	🟢 Ready	View Preview	Jul 14, 2026, 9:55 PM

greptile-apps · 2026-07-14T21:57:45Z

Greptile Summary

This PR reworks OutgoingTransactionFailureReason to expose only integrator-actionable outcomes: four internal-step values (EXECUTION_FAILED_POST_DEBIT, SETTLEMENT_FAILED, TIMEOUT, MANUAL_REFUND) are removed, five granular payout-partner reasons are added (PAYOUT_RETURNED, LIMIT_EXCEEDED, ACCOUNT_CANNOT_RECEIVE, ACCOUNT_INVALID, COMPLIANCE_REJECTED), and the two deprecated legacy values are retained at the tail of the enum for backward compatibility. Docs in transaction-lifecycle.mdx and the error-handling.mdx snippet are updated to match.

OpenAPI source and bundles — OutgoingTransactionFailureReason.yaml is the authoritative change; openapi.yaml and mintlify/openapi.yaml are correctly regenerated bundles with an inline Markdown table added to the description.
transaction-lifecycle.mdx — failure-reason table rewritten to reflect the new enum; the FAILED webhook example is corrected from the non-existent INVALID_BANK_ACCOUNT to ACCOUNT_INVALID; a trailing note covers deprecated values.
error-handling.mdx — five new payout reasons added to the outgoing-failures list, matching the enum order.

Confidence Score: 5/5

Safe to merge. The enum and docs changes are well-scoped and internally consistent; the only gaps are documentation omissions of SCA_NOT_COMPLETED.
The OpenAPI source, both generated bundles, and the two docs files are all in sync with each other. The breaking change (enum value removals) is acknowledged with the correct label and the deprecated values are preserved for historical compatibility. No logic, auth, or data-handling code is affected.
transaction-lifecycle.mdx and error-handling.mdx are both missing SCA_NOT_COMPLETED from their failure-reason tables despite the PR calling it a distinct, actionable outcome.

Important Files Changed

Filename	Overview
openapi/components/schemas/transactions/OutgoingTransactionFailureReason.yaml	Enum reworked: 4 internal-only values removed, 5 granular payout reasons added, 2 deprecated values retained at end. Descriptions added as a Markdown table. Clean change consistent with the PR intent.
openapi.yaml	Generated bundle, correctly reflects the source enum change. Only the OutgoingTransactionFailureReason block changed; rest of spec is untouched.
mintlify/openapi.yaml	Mintlify-specific bundle, mirrors the openapi.yaml enum change identically. No other differences from the source spec change.
mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx	Failure-reason table updated to match new enum; FAILED webhook example corrected to ACCOUNT_INVALID; deprecated-values note added. SCA_NOT_COMPLETED (an active, actionable value) is absent from the table.
mintlify/snippets/error-handling.mdx	Five new payout failure reasons added to the snippet list. SCA_NOT_COMPLETED is still absent; the getUserFriendlyMessage code sample still maps the old INVALID_BANK_ACCOUNT key rather than the replacement values.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
TXN([Outgoing Transaction]) --> FAIL{Failed?}
FAIL -- No --> DONE([Completed])
FAIL -- Yes --> FR[failureReason]
FR --> PRE["Pre-execution\n─────────────\nQUOTE_EXPIRED\nFUNDING_AMOUNT_MISMATCH\nSCA_NOT_COMPLETED"]
FR --> EXEC["Execution\n─────────────\nQUOTE_EXECUTION_FAILED\n(covers full settlement path;\nauto-refund if debited)"]
FR --> PAYOUT["Payout-partner (NEW)\n─────────────\nPAYOUT_RETURNED\nLIMIT_EXCEEDED\nACCOUNT_CANNOT_RECEIVE\nACCOUNT_INVALID\nCOMPLIANCE_REJECTED"]
FR --> DEP["Deprecated / legacy\n─────────────\nLIGHTNING_PAYMENT_FAILED\nCOUNTERPARTY_POST_TX_FAILED"]
EXEC --> REFUND["Auto-refund initiated\n(track via refund object +\nOUTGOING_PAYMENT.REFUND_* events)"]
PAYOUT --> REFUND

_{Reviews (2): Last reviewed commit: "feat(openapi)!: drop internal-only outgo..." | Re-trigger Greptile}

greptile-apps · 2026-07-14T21:57:49Z

 **Common outgoing failure reasons:**

 - `QUOTE_EXPIRED` - Quote expired before execution
- `QUOTE_EXECUTION_FAILED` - Error executing the quote
+- `QUOTE_EXECUTION_FAILED` - Error executing the quote; no funds were debited
+- `EXECUTION_FAILED_POST_DEBIT` - Execution failed after debit; funds are refunded automatically
+- `SETTLEMENT_FAILED` - The settlement leg failed
 - `FUNDING_AMOUNT_MISMATCH` - Funding amount doesn't match expected amount
+- `TIMEOUT` - Transaction didn't complete within its processing window
+- `MANUAL_REFUND` - Transaction was refunded manually
+- `LSP_OPERATIONAL_FAILURE` - Lightspark-internal operational issue; contact Lightspark
+- `PAYOUT_RETURNED` - Receiving bank returned or reversed the payout
+- `LIMIT_EXCEEDED` - Payout exceeds a partner limit
+- `ACCOUNT_CANNOT_RECEIVE` - Recipient account can't accept the payment
+- `ACCOUNT_INVALID` - Recipient account details are wrong or not found
+- `COMPLIANCE_REJECTED` - Payout partner rejected on compliance grounds



Deprecated values not mentioned in snippet
transaction-lifecycle.mdx adds a note that LIGHTNING_PAYMENT_FAILED and COUNTERPARTY_POST_TX_FAILED may still be returned for historical transactions, but this snippet (which is the first error-handling reference many developers will read) has no equivalent callout. A developer whose integration receives a deprecated value for an older transaction will not find it in this list and may treat it as an unexpected/undocumented response.
Prompt To Fix With AI
This is a comment left during a code review. Path: mintlify/snippets/error-handling.mdx Line: 143-158 Comment: **Deprecated values not mentioned in snippet**`transaction-lifecycle.mdx` adds a note that `LIGHTNING_PAYMENT_FAILED` and `COUNTERPARTY_POST_TX_FAILED` may still be returned for historical transactions, but this snippet (which is the first error-handling reference many developers will read) has no equivalent callout. A developer whose integration receives a deprecated value for an older transaction will not find it in this list and may treat it as an unexpected/undocumented response. How can I resolve this? If you propose a fix, please make it concise.
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Add 7 counterparty (payout-side) reasons to OutgoingTransactionFailureReason so integrators can act on why a payout partner rejected or failed a transaction, rather than collapsing everything into the generic COUNTERPARTY_POST_TX_FAILED: - COUNTERPARTY_COMPLIANCE_REJECTED - COUNTERPARTY_ACCOUNT_INVALID - COUNTERPARTY_ACCOUNT_CANNOT_RECEIVE - COUNTERPARTY_LIMIT_EXCEEDED - COUNTERPARTY_PAYOUT_RETURNED - COUNTERPARTY_CURRENCY_EXCHANGE_FAILED - COUNTERPARTY_PAYOUT_EXPIRED Also document each value's customer-facing meaning in a markdown table, matching the OutgoingTransactionStatus convention. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Rename granular counterparty payout reasons (drop COUNTERPARTY_ prefix), remove COUNTERPARTY_CURRENCY_EXCHANGE_FAILED and COUNTERPARTY_PAYOUT_EXPIRED, and add EXECUTION_FAILED_POST_DEBIT, SETTLEMENT_FAILED, TIMEOUT, MANUAL_REFUND, and LSP_OPERATIONAL_FAILURE. Mark LIGHTNING_PAYMENT_FAILED and COUNTERPARTY_POST_TX_FAILED as deprecated/legacy. Update transaction lifecycle and error handling docs accordingly. Co-authored-by: Cursor <cursoragent@cursor.com>

Align the MDX failure-reason references with OutgoingTransactionFailureReason: drop the non-existent INSUFFICIENT_BALANCE, add TIMEOUT and MANUAL_REFUND (plus SETTLEMENT_FAILED in the error-handling snippet), reorder to enum order, and fix the FAILED webhook example to use ACCOUNT_INVALID. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Remove the negative guarantee from QUOTE_EXECUTION_FAILED across the enum description and docs. EXECUTION_FAILED_POST_DEBIT still carries the affirmative "debited then refunded automatically" wording. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions · 2026-08-13T15:46:57Z

✱ Stainless preview builds for grid

This PR will update the grid SDKs with the following commit messages.

cli

chore(internal): regenerate SDK with no functional changes

go

feat(api): add failure reason enum values to OutgoingTransaction

kotlin

feat(api): add failure reason enum values to OutgoingTransaction

openapi

feat(api): add payout/operational failure reason enum values

php

feat(api): add failure reasons to OutgoingTransaction FailureReason enum

python

feat(api): add failure reason values to outgoing_transaction

ruby

feat(api): add failure reasons to OutgoingTransaction

typescript

feat(api): add failure reasons to OutgoingTransaction

⚠️

grid-openapistudio · code

Your SDK build had at least one "warning" diagnostic.
generate ⚠️

✅ grid-rubystudio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ✅ → lint ✅ → test ✅

⚠️

grid-gostudio · code

Your SDK build had a failure in the lint CI job, which is a regression from the base state.
generate ✅ → build ✅ → lint ❗ → test ❗
go get github.com/stainless-sdks/grid-go@f7fb47259dfd8c6f42ae63a91977140e56066a84

⚠️

grid-kotlinstudio · code

Your SDK build had a failure in the test CI job, which is a regression from the base state.
generate ⚠️ → build ✅ → lint ✅ → test ❗

✅ grid-typescriptstudio · conflict

Your SDK build had at least one note diagnostic.

⚠️

grid-pythonstudio · code

Your SDK build had a failure in the lint CI job, which is a regression from the base state.
generate ✅ → build ✅ → lint ❗ → test ❗
pip install https://pkg.stainless.com/s/grid-python/a7be8be1e0b10596fb9a0de596dba544726657ff/grid-0.0.1-py3-none-any.whl

✅ grid-phpstudio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → lint ✅ → test ✅

⚠️

grid-clistudio · code

Your SDK build had a failure in the test CI job, which is a regression from the base state.
generate ⚠️ → build ⏭️ → lint ⏭️ → test ❗

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-08-13 20:07:23 UTC

github-actions · 2026-08-13T17:27:00Z

⚠️ Breaking OpenAPI changes detected

oasdiff reports 9 error / 85 warning changes to openapi.yaml.
This PR will need approval from an API reviewer before merge.

Errors (9)

POST /stablecoins/{stablecoinId}/burns — added the new required request property source/oneOf[subschema #1: External Account]/allOf[subschema #2]/externalAccountId [new-required-request-property].
POST webhook:agent-action — removed the enum value EXECUTION_FAILED_POST_DEBIT of the request property allOf[subschema #2]/data/transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason [request-property-enum-value-removed].
POST webhook:agent-action — removed the enum value MANUAL_REFUND of the request property allOf[subschema #2]/data/transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason [request-property-enum-value-removed].
POST webhook:agent-action — removed the enum value SETTLEMENT_FAILED of the request property allOf[subschema #2]/data/transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason [request-property-enum-value-removed].
POST webhook:agent-action — removed the enum value TIMEOUT of the request property allOf[subschema #2]/data/transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason [request-property-enum-value-removed].
POST webhook:outgoing-payment — removed the enum value EXECUTION_FAILED_POST_DEBIT of the request property allOf[subschema #2]/data/allOf[subschema #2]/failureReason [request-property-enum-value-removed].
POST webhook:outgoing-payment — removed the enum value MANUAL_REFUND of the request property allOf[subschema #2]/data/allOf[subschema #2]/failureReason [request-property-enum-value-removed].
POST webhook:outgoing-payment — removed the enum value SETTLEMENT_FAILED of the request property allOf[subschema #2]/data/allOf[subschema #2]/failureReason [request-property-enum-value-removed].
POST webhook:outgoing-payment — removed the enum value TIMEOUT of the request property allOf[subschema #2]/data/allOf[subschema #2]/failureReason [request-property-enum-value-removed].

Warnings (85)

Show sample

GET /agents/approvals — added the new ACCOUNT_CANNOT_RECEIVE enum value to the data/items/transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
GET /agents/approvals — added the new ACCOUNT_INVALID enum value to the data/items/transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
GET /agents/approvals — added the new COMPLIANCE_REJECTED enum value to the data/items/transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
GET /agents/approvals — added the new LIMIT_EXCEEDED enum value to the data/items/transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
GET /agents/approvals — added the new PAYOUT_RETURNED enum value to the data/items/transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
GET /agents/me/actions — added the new ACCOUNT_CANNOT_RECEIVE enum value to the data/items/transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
GET /agents/me/actions — added the new ACCOUNT_INVALID enum value to the data/items/transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
GET /agents/me/actions — added the new COMPLIANCE_REJECTED enum value to the data/items/transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
GET /agents/me/actions — added the new LIMIT_EXCEEDED enum value to the data/items/transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
GET /agents/me/actions — added the new PAYOUT_RETURNED enum value to the data/items/transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
GET /agents/me/actions/{actionId} — added the new ACCOUNT_CANNOT_RECEIVE enum value to the transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
GET /agents/me/actions/{actionId} — added the new ACCOUNT_INVALID enum value to the transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
GET /agents/me/actions/{actionId} — added the new COMPLIANCE_REJECTED enum value to the transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
GET /agents/me/actions/{actionId} — added the new LIMIT_EXCEEDED enum value to the transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
GET /agents/me/actions/{actionId} — added the new PAYOUT_RETURNED enum value to the transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
POST /agents/me/quotes/{quoteId}/execute — added the new ACCOUNT_CANNOT_RECEIVE enum value to the transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
POST /agents/me/quotes/{quoteId}/execute — added the new ACCOUNT_INVALID enum value to the transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
POST /agents/me/quotes/{quoteId}/execute — added the new COMPLIANCE_REJECTED enum value to the transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
POST /agents/me/quotes/{quoteId}/execute — added the new LIMIT_EXCEEDED enum value to the transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
POST /agents/me/quotes/{quoteId}/execute — added the new PAYOUT_RETURNED enum value to the transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
GET /agents/me/transactions — added the new ACCOUNT_CANNOT_RECEIVE enum value to the data/items/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
GET /agents/me/transactions — added the new ACCOUNT_INVALID enum value to the data/items/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
GET /agents/me/transactions — added the new COMPLIANCE_REJECTED enum value to the data/items/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
GET /agents/me/transactions — added the new LIMIT_EXCEEDED enum value to the data/items/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
GET /agents/me/transactions — added the new PAYOUT_RETURNED enum value to the data/items/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/failureReason response property for the response status 200 [response-property-enum-value-added]. Adding new enum values to response could be unexpected for clients, use x-extensible-enum instead.
…and 60 more warnings.

Detected by oasdiff. Full report: job summary or the oasdiff-report artifact.

The value is never returned. An operational failure on the provider side reaches integrators as QUOTE_EXECUTION_FAILED, which is the same outcome to act on, so the finer distinction has no public meaning. #629 made this call when it added the other missing enum members; this branch reintroduced it by mistake. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Removes the four values #629 added. Each describes an internal step of how a payment is processed rather than an outcome an integrator acts on differently: - EXECUTION_FAILED_POST_DEBIT and SETTLEMENT_FAILED say where on the way to settlement the failure happened. Both collapse into QUOTE_EXECUTION_FAILED, whose description now covers that whole path and states that a debited amount is refunded automatically. - TIMEOUT and MANUAL_REFUND describe operator-initiated refunds. That outcome already surfaces on the refund object, whose reason enum carries TIMEOUT and USER_CANCELLATION. LIGHTNING_PAYMENT_FAILED's deprecation note now points at QUOTE_EXECUTION_FAILED rather than the removed SETTLEMENT_FAILED. BREAKING CHANGE: four values are removed from OutgoingTransactionFailureReason. The server-side mapping for them has to be updated before clients are regenerated, or failureReason renders empty — see #629. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

mintlifyBotdeployed to staging - mintlify July 14, 2026 21:55 View deployment

greptile-appsBot reviewed Jul 14, 2026
View reviewed changes

mintlifyBotdeployed to staging - mintlify July 14, 2026 22:48 View deployment

jklein24 approved these changes Jul 30, 2026
View reviewed changes

JasonCWang marked this pull request as draft August 7, 2026 17:06

JasonCWangand others added 4 commits August 13, 2026 08:43

JasonCWang force-pushed the feat/outgoing-counterparty-failure-reasons branch from 333b174 to 69fd0d8Compare August 13, 2026 15:46

mintlifyBotdeployed to staging - mintlify August 13, 2026 15:47 View deployment

mintlifyBotdeployed to staging - mintlify August 13, 2026 16:13 View deployment

github-actionsBot added the breaking-change Introduces a breaking change to the OpenAPI spec label Aug 13, 2026

mintlifyBotdeployed to staging - mintlify August 13, 2026 17:28 View deployment

JasonCWang force-pushed the feat/outgoing-counterparty-failure-reasons branch from 07cc8b8 to 2a4c7cfCompare August 13, 2026 17:34

mintlifyBotdeployed to staging - mintlify August 13, 2026 17:36 View deployment

JasonCWang changed the title ~~feat: add granular counterparty payout failure reasons~~feat!: granular counterparty payout failure reasons, drop internal-only onesAug 13, 2026

JasonCWang force-pushed the feat/outgoing-counterparty-failure-reasons branch from 2a4c7cf to aa9f595Compare August 13, 2026 17:46

mintlifyBotdeployed to staging - mintlify August 13, 2026 17:47 View deployment

JasonCWangand others added 2 commits August 13, 2026 11:01

JasonCWang force-pushed the feat/outgoing-counterparty-failure-reasons branch from aa9f595 to 6b40894Compare August 13, 2026 18:02

mintlifyBotdeployed to staging - mintlify August 13, 2026 18:03 View deployment

JasonCWang marked this pull request as ready for review August 13, 2026 18:04

shreyav approved these changes Aug 13, 2026
View reviewed changes

JasonCWang merged commit f0176f1 into mainAug 13, 2026
10 checks passed

JasonCWang deleted the feat/outgoing-counterparty-failure-reasons branch August 13, 2026 20:00

JasonCWang changed the title ~~feat!: granular counterparty payout failure reasons, drop internal-only ones~~feat!: granular counterparty payout failure reasonsAug 13, 2026

ls-boltBot mentioned this pull request Aug 13, 2026
Add compliance context to transactions #823
Merged

Navigation Menu

Uh oh!

feat!: granular counterparty payout failure reasons - #689

feat!: granular counterparty payout failure reasons#689
JasonCWang merged 6 commits into
mainfrom
feat/outgoing-counterparty-failure-reasons

JasonCWang commented Jul 14, 2026•
edited
Loading

Uh oh!

vercelBot commented Jul 14, 2026•
edited
Loading

Uh oh!

mintlifyBot commented Jul 14, 2026•
edited
Loading

Uh oh!

greptile-appsBot commented Jul 14, 2026•
edited
Loading

Important Files Changed

Flowchart

Uh oh!

greptile-appsBotJul 14, 2026

Uh oh!

github-actionsBot commented Aug 13, 2026•
edited
Loading

Uh oh!

github-actionsBot commented Aug 13, 2026•
edited
Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

JasonCWang commented Jul 14, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Breaking change

Changes

Test plan

Uh oh!

vercelBot commented Jul 14, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mintlifyBot commented Jul 14, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

greptile-appsBot commented Jul 14, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Flowchart

Uh oh!

greptile-appsBotJul 14, 2026

Choose a reason for hiding this comment

Uh oh!

github-actionsBot commented Aug 13, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✱ Stainless preview builds for grid

Uh oh!

github-actionsBot commented Aug 13, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ Breaking OpenAPI changes detected

Errors (9)

Warnings (85)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

JasonCWang commented Jul 14, 2026•
edited
Loading

vercelBot commented Jul 14, 2026•
edited
Loading

mintlifyBot commented Jul 14, 2026•
edited
Loading

greptile-appsBot commented Jul 14, 2026•
edited
Loading

github-actionsBot commented Aug 13, 2026•
edited
Loading

github-actionsBot commented Aug 13, 2026•
edited
Loading