docs(transactions): document the 501 response on the cancel endpoint

[ls-bolt]

Summary

• POST /transactions/{transactionId}/cancel returns 501 NOT_IMPLEMENTED for any payment rail whose banking partner exposes no cancellation facility, but the spec never documented a 501 response. Integrators hit an undocumented status on the endpoint's primary path.
• Adds the 501 response (Error501, already used by /cards, /customers, and /platform/config).
• Rewrites the 200 description: a success means the banking partner accepted the cancellation request, not that the transfer is already cancelled. The partner confirms asynchronously, so the transaction body returned may still report its pre-cancellation status.

Changes: 3 files

• openapi/paths/transactions/transactions_{transactionId}_cancel.yaml — add 501, clarify 200
• openapi.yaml, mintlify/openapi.yaml — regenerated bundles (npm run build:openapi)

Net diff is confined to the cancel path. npm run lint passes.

Requested by @AaryamanBhute

[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 6, 2026 5:39pm
grid-wallet-demo	Ignored	Preview	Aug 6, 2026 5:39pm

[akanter]

• docs(transactions): document the 501 response on the cancel endpoint #774 👈 (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

chore(internal): regenerate SDK with no functional changes

kotlin

chore(internal): regenerate SDK with no functional changes

openapi

feat(api): add 501 error response to transactions cancel method

php

chore(internal): regenerate SDK with no functional changes

python

chore(internal): regenerate SDK with no functional changes

ruby

chore(internal): regenerate SDK with no functional changes

typescript

chore(internal): regenerate SDK with no functional changes

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

✅ grid-typescript studio · code · diff

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

✅ 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 ⏭️ (prev: build ✅) → lint ✅ → test ✅

✅ grid-go studio · code · diff

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

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

✅ grid-kotlin studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → build ⏭️ (prev: build ✅) → lint ⏭️ (prev: 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 ⏭️ (prev: build ✅) → lint ⏭️ (prev: 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 ❗

---

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-07-30 19:30:36 UTC

[mintlify]

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

Project	Status	Preview	Updated (UTC)
Grid	🟢 Ready	View Preview	Jul 30, 2026, 7:23 PM

[ls-bolt]

Ready for review — the implementation it documents has merged

lightsparkdev/webdev#31504 merged, so POST /transactions/{transactionId}/cancel now returns 501 NOT_IMPLEMENTED in production for rails without cancellation support. That response is still undocumented in the public spec, which this PR fixes.

Refreshed in 0974dfd0:

• Rebased onto main (was 24 commits behind) and rebuilt the bundles. The stale base previously produced a false "removed enum value" breaking-change report; net diff vs main is now exactly the cancel path.
• Reworded the 501 to match what actually shipped. My original text blamed the rail — "banking partner ... exposing a cancellation facility" — which @whoisglover corrected on the webdev PR: Lead's API does expose ACH/wire/instant cancel endpoints, we simply haven't implemented the manager override. It now reads "not yet available ... support is being rolled out per rail and per banking partner", which is honest about it being our gap.

The 200 reword also stands: a success means the partner accepted the request, not that the transfer is already cancelled — it confirms asynchronously via webhook, so the returned transaction may still show its pre-cancellation status.

npm run lint passes.

---

🤖 tidal-channel(#6) | Feedback

[ls-bolt]

Heads-up: the green checkmark here is thinner than it looks

The rollup on 0974dfd0 reads SUCCESS, but only Vercel and Mintlify ran. The four workflows that actually validate this change — Lint, OpenAPI Breaking Changes, OpenAPI Documentation Build, Build SDKs — did not fire on this push, even though they ran on the previous SHA of this same branch and are path-filtered on openapi/** + openapi.yaml, which this push touches.

I can't re-run workflows (Resource not accessible by integration), so I ran their local equivalents instead of reporting a green I don't trust:

• Lint — npm run lint exits 0. "Woohoo! Your API description is valid." The remaining warnings are pre-existing schema-properties-have-descriptions on unrelated Cad/Cop schemas.
• Breaking changes — verified by hand, since the change is purely additive. The complete set of removed lines vs main is one line:

  -          description: Cancellation requested successfully
  

  No field, response, or enum value is removed. I also diffed every enum value in main's bundle against mine: nothing dropped (this is the check that produced a false positive last time, when the branch was stale — it's now rebased onto main).

So the change is sound, but someone with write access may want to push an empty commit or re-run the workflows before merge if the four checks are required. Flagging rather than assuming the checkmark speaks for them.

---

🤖 tidal-channel(#6) | Feedback

[ls-bolt]

Correction + final CI read on 0974dfd0

Correcting my earlier comment: I said the four OpenAPI workflows "did not fire on this push." That was true when I wrote it but wrong now — they were delayed, not skipped, and all four have since run. Disregard the suggestion to push an empty commit to trigger them.

Where they landed:

Check	Result
Detect breaking changes	✅ success
Build OpenAPI Documentation	✅ success
Lint Code & Documentation	⚠️ cancelled (run reports failure)
preview (Stainless SDK build)	❌ failure
Mintlify / Vercel	✅ success

Detect breaking changes passing is the one that matters here — it independently confirms the hand-verification I posted above, and it's the check that produced a false breaking-change report when this branch was 24 commits stale. The rebase fixed that.

Both reds are infrastructure, not this spec:

• preview — Stainless's API returned HTTP 503: upstream connect error ... reset reason: overflow during OIDC auth. The action never reached the spec. The same job passed on this branch's previous SHA with a near-identical diff.
• Lint — the job is cancelled with no failed step and no logs, i.e. aborted before producing output; the run-level failure is inherited from that. I ran the exact CI command locally — make lint — and it exits 0. The remaining output is pre-existing information/warning findings on unrelated Cad/Cop/Eur/Gbp beneficiary schemas, none of them mine. Another PR's Lint (39798cfb) also failed today, so this isn't specific to this branch.

Both need a re-run once Stainless recovers, which I can't do (Resource not accessible by integration).

---

🤖 tidal-channel(#6) | Feedback