feat: add QUOTE_RATE_UNAVAILABLE outgoing transaction failure reason

mintlify/platform-overview/core-concepts/quote-system.mdx

@@ -454,12 +454,16 @@ For cross-currency quotes the exchange rate applies on top of this: the fee is t
     try {
       await executeQuote(quote.id);
     } catch (error) {
-      if (error.code === 'QUOTE_EXPIRED') {
+      if (error.code === 'QUOTE_EXPIRED' || error.code === 'QUOTE_RATE_UNAVAILABLE') {
         quote = await createQuote(quoteParams); // Recreate with fresh rate
         await executeQuote(quote.id);
       }
     }
     ```
+
+    `QUOTE_RATE_UNAVAILABLE` means the quoted rate was refused when the quote was
+    executed, rather than the quote's own expiry window elapsing. Nothing was
+    exchanged in either case, and the recovery is the same: create a new quote.
   </Accordion>
 
   <Accordion title="Monitor quote status via webhooks">

mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx

@@ -483,6 +483,7 @@ Use for reconciliation and reporting.
 | Failure Reason | Description | Recovery |
 |----------------|-------------|----------|
 | `QUOTE_EXPIRED` | Quote expired before execution | Create new quote |
+| `QUOTE_RATE_UNAVAILABLE` | Quoted exchange rate was refused at execution; nothing was exchanged | Create new quote |
 | `QUOTE_EXECUTION_FAILED` | Error executing the quote; a debited amount is refunded automatically | Create new quote |
 | `FUNDING_AMOUNT_MISMATCH` | Funding amount doesn't match expected amount | Verify amounts and retry |
 | `PAYOUT_RETURNED` | Receiving bank returned or reversed the payout | Verify details and retry |

mintlify/ramps/conversion-flows/fiat-crypto-conversion.mdx

@@ -239,13 +239,13 @@ curl -X POST 'https://api.lightspark.com/grid/2025-10-13/quotes' \
 <AccordionGroup>
 <Accordion title="Handle quote expiration">
 ```javascript
-async function refreshQuoteIfNeeded(quote) {
+async function refreshQuoteIfNeeded(quote, quoteRequest) {
   const expiresAt = new Date(quote.expiresAt);
   const now = new Date();
 
   if (expiresAt - now < 60000) {
     // Less than 1 minute left
-    return await createNewQuote(quote.originalParams);
+    return await createNewQuote(quoteRequest);
   }
 
   return quote;
@@ -267,15 +267,22 @@ const settlementTimes = {
 
 <Accordion title="Handle failed transactions">
 ```javascript
-if (transaction.status === "FAILED") {
+// quoteRequest is the request your integration sent to create the original
+// quote: a transaction does not carry the parameters it was quoted from.
+async function handleFailedTransaction(transaction, quoteRequest) {
+  if (transaction.status !== "FAILED") return;
+
   await notifyUser(transaction.customerId, {
     message: "Transaction failed",
     reason: transaction.failureReason,
     action: "retry",
   });
 
-  if (transaction.failureReason === "QUOTE_EXPIRED") {
-    await createNewQuote(transaction.originalParams);
+  if (
+    transaction.failureReason === "QUOTE_EXPIRED" ||
+    transaction.failureReason === "QUOTE_RATE_UNAVAILABLE"
+  ) {
+    await createNewQuote(quoteRequest);
   }
 }
 ```

mintlify/snippets/error-handling.mdx

@@ -204,6 +204,7 @@ When a transaction fails, the `failureReason` field provides specific details:
 **Common outgoing failure reasons:**
 
 - `QUOTE_EXPIRED` - Quote expired before execution
+- `QUOTE_RATE_UNAVAILABLE` - Quoted exchange rate was refused at execution; nothing was exchanged
 - `QUOTE_EXECUTION_FAILED` - Error executing the quote; a debited amount is refunded automatically
 - `FUNDING_AMOUNT_MISMATCH` - Funding amount doesn't match expected amount
 - `PAYOUT_RETURNED` - Receiving bank returned or reversed the payout
@@ -438,6 +439,7 @@ Convert technical errors to user-friendly messages:
 function getUserFriendlyMessage(error) {
   const errorMessages = {
     QUOTE_EXPIRED: "Exchange rate expired. Please try again.",
+    QUOTE_RATE_UNAVAILABLE: "Exchange rate is no longer available. Please try again.",
     INSUFFICIENT_BALANCE: "You don't have enough funds for this payment.",
     INVALID_BANK_ACCOUNT:
       "Bank account details are invalid. Please check and try again.",

openapi/components/schemas/transactions/OutgoingTransactionFailureReason.yaml

@@ -1,6 +1,7 @@
 type: string
 enum:
   - QUOTE_EXPIRED
+  - QUOTE_RATE_UNAVAILABLE
   - QUOTE_EXECUTION_FAILED
   - FUNDING_AMOUNT_MISMATCH
   - SCA_NOT_COMPLETED
@@ -31,6 +32,7 @@ description: |
   | Reason | Description |
   |--------|-------------|
   | `QUOTE_EXPIRED` | The quote was not executed before its expiry window |
+  | `QUOTE_RATE_UNAVAILABLE` | The quoted exchange rate was no longer available when the quote was executed, so nothing was exchanged. Create a new quote to get a current rate |
   | `QUOTE_EXECUTION_FAILED` | The quote could not be executed. Covers any internal failure on the way to settlement, whether or not funds were debited — a debited amount is refunded automatically |
   | `FUNDING_AMOUNT_MISMATCH` | The funds received did not match the expected amount |
   | `SCA_NOT_COMPLETED` | The customer did not complete the Strong Customer Authentication challenge before it expired |