docs(spec): correct quote expiresAt window, document 501 on /cards, add 429 to verify

openapi/components/schemas/quotes/Quote.yaml

@@ -36,7 +36,14 @@ properties:
   expiresAt:
     type: string
     format: date-time
-    description: When this quote expires (typically 1-5 minutes after creation)
+    description: >-
+      Absolute UTC timestamp when the rate locked in this quote becomes
+      invalid and the quote can no longer be executed. The window depends
+      on the rail and corridor: instant rails (Lightning, Spark, USDC on
+      Solana/Base/Polygon, RTP, SEPA Instant) typically expire in 1–5
+      minutes; corridors with longer settlement guarantees may have longer
+      windows. Always rely on this timestamp rather than assuming a fixed
+      window.
     example: '2025-10-03T12:05:00Z'
   # Transfer details
   source:

openapi/paths/auth/auth_credentials_{id}_verify.yaml

@@ -108,6 +108,22 @@ post:
         application/json:
           schema:
             $ref: ../../components/schemas/errors/Error404.yaml
+    '429':
+      description: >-
+        Too many requests. Returned with `RATE_LIMITED` when verification
+        attempts for this credential happen too frequently (for example,
+        repeated bad OTPs or rapid-fire reauthentication retries). Clients
+        should back off and retry after the interval indicated by the
+        `Retry-After` response header.
+      headers:
+        Retry-After:
+          description: Number of seconds to wait before retrying the request.
+          schema:
+            type: integer
+      content:
+        application/json:
+          schema:
+            $ref: ../../components/schemas/errors/Error429.yaml
     '500':
       description: Internal service error
       content:

openapi/paths/auth/auth_sessions_{id}.yaml

@@ -15,6 +15,15 @@ delete:
     then retry the same `DELETE` request with that full stamp as the
     `Grid-Wallet-Signature` header and the `requestId` echoed back as
     the `Request-Id` header. The signed retry returns `204`.
+
+
+    Sessions also expire on their own. `404` is returned whenever the
+    `id` does not match an active session — whether the session was
+    never issued, was already revoked by a prior call, or has expired
+    past its `expiresAt`. The response code reflects the resource
+    state, not an error in the client's flow: re-revoking an
+    already-revoked or expired session is safe and idempotent at the
+    user intent level.
   operationId: revokeAuthSession
   tags:
     - Embedded Wallet Auth

openapi/paths/cards/cards.yaml

@@ -61,6 +61,15 @@ post:
         application/json:
           schema:
             $ref: ../../components/schemas/errors/Error500.yaml
+    '501':
+      description: >-
+        Not implemented in this environment. Card issuance is not enabled
+        for every Grid deployment; environments without a configured card
+        issuer return `501 NOT_IMPLEMENTED`.
+      content:
+        application/json:
+          schema:
+            $ref: ../../components/schemas/errors/Error501.yaml
 get:
   summary: List cards
   description: >
@@ -150,3 +159,12 @@ get:
         application/json:
           schema:
             $ref: ../../components/schemas/errors/Error500.yaml
+    '501':
+      description: >-
+        Not implemented in this environment. Cards are not enabled for
+        every Grid deployment; environments without a configured card
+        issuer return `501 NOT_IMPLEMENTED`.
+      content:
+        application/json:
+          schema:
+            $ref: ../../components/schemas/errors/Error501.yaml