feat: add QUOTE_RATE_UNAVAILABLE outgoing transaction failure reason

[jklein24]

Summary

• Adds QUOTE_RATE_UNAVAILABLE to OutgoingTransactionFailureReason, for a quote whose exchange rate was refused at execution time
• Today that outcome is reported as QUOTE_EXPIRED, which is indistinguishable from a quote whose expiry window genuinely elapsed. Both mean nothing was exchanged, but only one is about timing, and only one is fixed by executing faster
• Documents the recovery in the quote-system guide alongside the existing QUOTE_EXPIRED example: identical (create a new quote), so callers can handle both together

Changes: 4 files

• openapi/components/schemas/transactions/OutgoingTransactionFailureReason.yaml — new enum value + description-table row
• openapi.yaml, mintlify/openapi.yaml — rebundled (npm run build:openapi)
• mintlify/platform-overview/core-concepts/quote-system.mdx — error-handling example covers both codes

Test plan

• make lint-openapi — "Woohoo! Your API description is valid. 🎉"
• Adding an enum value is additive, but a caller switching exhaustively on failure reasons will see a new variant — flagging for the openapi-breaking-changes check rather than working around it

Requested by @jklein24

Original PR: #846

[vercel]

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 19, 2026 8:55pm
grid-wallet-demo	Ignored	Preview	Aug 19, 2026 8:55pm

[lightspark-bot]

• feat: add QUOTE_RATE_UNAVAILABLE outgoing transaction failure reason #847 👈 (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

go

feat(types): add QUOTE_RATE_UNAVAILABLE to OutgoingTransactionFailureReason

kotlin

feat(api): add QUOTE_RATE_UNAVAILABLE to OutgoingTransaction FailureReason enum

openapi

feat(api): add QUOTE_RATE_UNAVAILABLE to quote failure reason enum

php

feat(api): add QUOTE_RATE_UNAVAILABLE to FailureReason enum

python

feat(api): add QUOTE_RATE_UNAVAILABLE to failure_reason in OutgoingTransaction

ruby

feat(api): add QUOTE_RATE_UNAVAILABLE to outgoing_transaction failure_reason

typescript

feat(api): add QUOTE_RATE_UNAVAILABLE to OutgoingTransaction.failureReason

⚠️ grid-openapi studio · code

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

⚠️ grid-ruby studio · code

Your SDK build had at least one "warning" diagnostic.
generate ⚠️ → build ✅ → lint ✅ → test ✅

⚠️ grid-go studio · 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@00f0810251859aab2c338fb3db1682e7ef92ef0b

⚠️ grid-kotlin studio · 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-typescript studio · conflict

Your SDK build had at least one warning diagnostic.

⚠️ grid-python studio · 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/28cae985f883ee56bd86cc3d2f8982d24b166842/grid-0.0.1-py3-none-any.whl

⚠️ grid-php studio · code

Your SDK build had at least one "warning" diagnostic.
generate ⚠️ → lint ✅ → test ✅

⚠️ grid-cli studio · 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-20 01:33:20 UTC

[greptile-apps]

Greptile Summary

      ⚡      ☠      ⚡
   ___/|  GRID RIFF  |\___
  /___ |___ METAL ___| ___\
       \m/         \m/

QUOTE RATE UNAVAILABLE — forge the failure contract in steel.

This PR distinguishes execution-time exchange-rate refusal from genuine quote expiry and documents the shared create-a-new-quote recovery.

• Adds QUOTE_RATE_UNAVAILABLE to the outgoing transaction failure-reason schema and synchronized OpenAPI bundles.
• Updates lifecycle, error-handling, quote-system, and fiat-to-crypto guidance.
• Reworks the previously flagged recovery examples to accept the caller’s original quote request instead of reading nonexistent transaction or quote fields.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
openapi/components/schemas/transactions/OutgoingTransactionFailureReason.yaml	Adds the outgoing QUOTE_RATE_UNAVAILABLE enum value and clearly documents its meaning and recovery.
openapi.yaml	Keeps the committed root OpenAPI bundle synchronized with the modular source schema.
mintlify/openapi.yaml	Keeps the Mintlify OpenAPI bundle synchronized with the source and root bundle.
mintlify/platform-overview/core-concepts/quote-system.mdx	Documents the distinction between rate refusal and expiry while prescribing the same fresh-quote recovery.
mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx	Adds the new outgoing failure reason to the lifecycle recovery table.
mintlify/ramps/conversion-flows/fiat-crypto-conversion.mdx	Updates both recovery snippets to receive the integration’s original quote request explicitly.
mintlify/snippets/error-handling.mdx	Adds the new failure reason to the outgoing reference list and user-facing message mapping.

_{Reviews (6): Last reviewed commit: "feat: add QUOTE_RATE_UNAVAILABLE outgoin..." | Re-trigger Greptile}

[ls-bolt]

⚡ Revision log — updated in place, latest first.

Revision 2

• Failed-transaction recovery example is now a self-contained handleFailedTransaction(transaction, quoteRequest); it re-sends the caller's original quote request instead of inventing transaction.originalParams or rebuilding an ACCOUNT source this page's REALTIME_FUNDING flow never has
• Adjacent refreshQuoteIfNeeded now takes the same quoteRequest rather than the non-existent quote.originalParams — the pre-existing sibling defect @greptile-apps and I both flagged
• No spec changes in this round; the enum and generated bundles are unchanged since the first review

Earlier revisions (1)

Revision 1

• Added QUOTE_RATE_UNAVAILABLE to the outgoing failure-reason list and the user-message map in snippets/error-handling.mdx — per @greptile-apps, the new code appeared in no reference list
• Added it to the failure-reason table in transaction-lifecycle.mdx and to the transaction.failureReason example in fiat-crypto-conversion.mdx, both with the same create-a-new-quote recovery
• Kept error.code in the quote-system example: the execute endpoint really does return this code (webdev#33029 asserts it on the wire), and QUOTE_EXPIRED is documented on both surfaces already — explained in the thread
• Left IncomingTransactionFailureReason alone: a rate refusal happens on the outgoing leg, so it cannot occur incoming

[greptile-apps]

The revision covers everything. Both issues from my original comments are addressed:

• The missing-reference-list gap (P2) is closed — QUOTE_RATE_UNAVAILABLE now appears in the failure-reason list, error-handling.mdx, transaction-lifecycle.mdx, and fiat-crypto-conversion.mdx
• error.code in the quote-system example is correct and I already updated my comment on that thread
• Leaving IncomingTransactionFailureReason alone is right — the rate refusal is on the outgoing swap leg

No further action needed from my side. LGTM.

[ls-bolt]

@greptile review

[ls-bolt]

@greptile review

[ls-bolt]

@greptile review

[ls-bolt]

@greptile review

[ls-bolt]

@greptile review

[greptile-apps]

Revision 2 fully resolves what my summary flagged. The current fiat-crypto-conversion.mdx is correct on both fronts:

• refreshQuoteIfNeeded(quote, quoteRequest) → createNewQuote(quoteRequest): quote.originalParams is gone.
• handleFailedTransaction(transaction, quoteRequest) is self-contained, accepts the caller's original quote request, and handles both QUOTE_EXPIRED and QUOTE_RATE_UNAVAILABLE without touching any fabricated field.

My "not yet safe to merge" note in the summary was written before this push and is no longer accurate. LGTM.