Add missing OutgoingTransactionFailureReason enum values

[peterrojs]

Summary

Adds four missing values to the public OutgoingTransactionFailureReason enum so the Grid API can represent the full set of failure reasons the backend actually emits:

• EXECUTION_FAILED_POST_DEBIT
• SETTLEMENT_FAILED
• TIMEOUT
• MANUAL_REFUND

Why

sparkcore maps its internal UmaaasSendOperationFailureReason onto this public enum by name (sparkcore/grid/objects/transaction.py::_get_outgoing_transaction_failure_reason). The internal enum has these four members but the public enum didn't, so the mapping threw a (caught) KeyError, logged "Key does not exist in GridOutgoingTransactionFailureReason", and returned None — meaning the API reported an empty failure reason for settlement / timeout / manual-refund / post-debit failures, plus noisy ERROR logs on every render of such a transaction.

Surfaced while debugging the embedded-USDB onramp failures (those failed send-operations carry SETTLEMENT_FAILED).

What changed

• openapi/components/schemas/transactions/OutgoingTransactionFailureReason.yaml — source enum (the only hand edit)
• openapi.yaml + mintlify/openapi.yaml — regenerated via make build (redocly bundle)

Notes / decisions

• LSP_OPERATIONAL_FAILURE intentionally NOT added — sparkcore deliberately maps it to QUOTE_EXECUTION_FAILED (internal-only distinction for LSP-liquidity alerting), so it should never reach the public enum.
• Alternative considered for EXECUTION_FAILED_POST_DEBIT: it's documented internally as an internal-only distinction (lets the compensation scanner safely credit). I chose to expose it for completeness so the mapping needs no special-case, but it could instead be mapped to QUOTE_EXECUTION_FAILED in sparkcore like LSP_OPERATIONAL_FAILURE. Easy to flip — happy to if you'd prefer to keep it internal.

Follow-up (separate PR, needed for the runtime fix)

This is the canonical spec change. webdev's vendored generated grid-api python package (webdev/grid-api, consumed by sparkcore as a path dep) must be regenerated from this spec via grid-api/update_schema.sh + a packageVersion bump + sparkcore/uv.lock update for sparkcore to actually pick up the new members. That regen needs the Java/Maven/openapi-generator toolchain and is a separate webdev PR — until it lands, sparkcore still KeyErrors.

Test plan

• make lint-openapi (redocly + spectral, --fail-severity=error) passes — no new findings
• Bundle is deterministic (clean rebuild produces no diff); change is exactly +4 enum lines across the source component and both bundled outputs

---

🤖 cryptic-tempest(#1) | Feedback

Original PR: #628

[akanter]

• Add missing OutgoingTransactionFailureReason enum values #629 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

✱ 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

csharp

feat(api): add 4 failure reason values to OutgoingTransactionFailureReason

go

feat(api): add failure reasons to OutgoingTransaction

kotlin

feat(api): add failure reason values to OutgoingTransaction

openapi

feat(api): add enum values to OutgoingTransactionFailureReason

php

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

python

feat(api): add failure reason values to outgoing_transaction

ruby

feat(api): add failure reason enum values to outgoing transaction

typescript

feat(api): add failure reason values to OutgoingTransaction

Edit this comment to update them. They will appear in their respective SDK's changelogs.

✅ grid-go studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ❗ → test ❗

go get github.com/stainless-sdks/grid-go@e159f26758cc048fe3afab5bd47c34b6ce25f2f2

✅ grid-typescript studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ✅ → test ✅

npm install https://pkg.stainless.com/s/grid-typescript/1178ef910e6e2f1036b8cc5f9c13ae521d0b49e2/dist.tar.gz

✅ grid-openapi studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️

✅ grid-ruby studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ✅ → test ✅

✅ grid-kotlin studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → build ✅ → lint ✅ → test ❗

✅ grid-csharp studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → build ❗ → lint ✅ → test ❗

✅ grid-php studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → lint ✅ → test ✅

✅ grid-cli studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → build ❗ → lint ❗ → test ❗

✅ grid-python studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ❗ → test ❗

pip install https://pkg.stainless.com/s/grid-python/e2d672961aeb811ea3de0195b3c830279b2908ea/grid-0.0.1-py3-none-any.whl

---

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-06-29 16:37:28 UTC

[greptile-apps]

Greptile Summary

Adds four missing OutgoingTransactionFailureReason enum values (EXECUTION_FAILED_POST_DEBIT, SETTLEMENT_FAILED, TIMEOUT, MANUAL_REFUND) to the public OpenAPI spec so it covers the full set of failure codes the backend can emit, eliminating the KeyError-and-None fallback in sparkcore's name-based mapping. The source YAML in openapi/ was edited directly and both bundled outputs were regenerated via make build, exactly following the repo's conventions.

• openapi/components/schemas/transactions/OutgoingTransactionFailureReason.yaml — the only hand-edited file; four enum values appended
• openapi.yaml + mintlify/openapi.yaml — deterministic regenerations via make build; diffs are identical and match the source edit exactly

Confidence Score: 5/5

Safe to merge — a minimal, additive enum extension with no breaking changes and both bundled outputs correctly regenerated.

The change is purely additive (new enum values only), the source file is the only hand-edited file, both bundles were regenerated via make build and produce identical diffs, make lint-openapi is confirmed passing, and LSP_OPERATIONAL_FAILURE is intentionally kept out with clear justification. No existing consumers break since the values were previously missing rather than having different names.

No files require special attention.

Important Files Changed

Filename	Overview
openapi/components/schemas/transactions/OutgoingTransactionFailureReason.yaml	Source enum extended with four new values; this is the only hand-edited file in the PR and the change is correct
openapi.yaml	Regenerated bundle (via make build); diff is exactly the four added enum lines, consistent with the source change
mintlify/openapi.yaml	Second regenerated bundle for Mintlify docs; identical diff to openapi.yaml, as expected

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[sparkcore internal\nUmaaasSendOperationFailureReason] -->|name-based mapping| B{Key in public\nGridOutgoingTransactionFailureReason?}
    B -->|Before this PR\nEXECUTION_FAILED_POST_DEBIT\nSETTLEMENT_FAILED\nTIMEOUT\nMANUAL_REFUND| C[KeyError → None\nblank failure reason]
    B -->|After this PR\nall four values added| D[Correct enum value\nreturned to API consumer]
    B -->|LSP_OPERATIONAL_FAILURE\nintentionally omitted| E[Maps to\nQUOTE_EXECUTION_FAILED]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[sparkcore internal\nUmaaasSendOperationFailureReason] -->|name-based mapping| B{Key in public\nGridOutgoingTransactionFailureReason?}
    B -->|Before this PR\nEXECUTION_FAILED_POST_DEBIT\nSETTLEMENT_FAILED\nTIMEOUT\nMANUAL_REFUND| C[KeyError → None\nblank failure reason]
    B -->|After this PR\nall four values added| D[Correct enum value\nreturned to API consumer]
    B -->|LSP_OPERATIONAL_FAILURE\nintentionally omitted| E[Maps to\nQUOTE_EXECUTION_FAILED]

Loading

_{Reviews (1): Last reviewed commit: "Add missing OutgoingTransactionFailureRe..." | Re-trigger Greptile}