feat(cards): add CARD_LIMIT_REACHED to the 409 error vocabulary by DhruvPareek · Pull Request #895 · lightsparkdev/grid-api

DhruvPareek · 2026-09-02T23:58:15Z

Reason

Grid is gaining a per-platform cap on how many live cards a platform may hold — a waitlist-style control so platforms can be onboarded to production card issuance a few cards at a time, with the allowance raised as they graduate.

Error409.code is a closed enum in the generated SDKs, so a client deserializing a rejection carrying an undocumented code fails validation instead of surfacing the error. The spec has to carry CARD_LIMIT_REACHED before the enforcement ships in sparkcore.

Overview

Error409.yaml — adds CARD_LIMIT_REACHED to the code enum and its description table.
paths/cards/cards.yaml — documents the cap in the POST /cards description, and adds the 409 response, which the endpoint had no entry for at all despite already returning CONFLICT for idempotency-key collisions.
Regenerated openapi.yaml / mintlify/openapi.yaml bundles.

Enforcement semantics the copy reflects: the cap counts live cards, so closing a card frees its slot, and CLOSED cards never count.

Test Plan

make build — bundle regenerates cleanly; the diff is limited to the two additions plus the new response block.
make lint — passes with 0 errors (901 pre-existing warnings/infos, unchanged by this PR).

🤖 Generated with Claude Code

https://claude.ai/code/session_012dsva2mXndRoAfUMb3vQCc

Grid is gaining a per-platform cap on how many live cards a platform may hold. Error409.code is a closed enum, so an SDK consumer deserializing the rejection would fail validation on an undocumented code; the spec has to carry it before the enforcement ships. Also documents the 409 response on POST /cards, which until now listed no 409 at all despite the endpoint already returning CONFLICT for idempotency-key collisions. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012dsva2mXndRoAfUMb3vQCc

vercel · 2026-09-02T23:58:17Z

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Actions	Updated
grid-flow-builder	Ignored	Preview	Sep 2, 2026 11:58pm UTC
grid-wallet-demo	Ignored	Preview	Sep 2, 2026 11:58pm UTC

DhruvPareek · 2026-09-02T23:58:27Z

feat(cards): add CARD_LIMIT_REACHED to the 409 error vocabulary #895 👈 (View in Graphite)
main

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

github-actions · 2026-09-02T23:58:52Z

✱ Stainless preview builds for grid

This PR will update the grid SDKs with the following commit messages.

cli
⏳ (generating...)```
feat(cards): add CARD_LIMIT_REACHED to the 409 error vocabulary

**go**

chore(internal): regenerate SDK with no functional changes

**kotlin**

docs(api): document card issuance limits in card issue method

**openapi**

feat(api): add 409 response and CARD_LIMIT_REACHED error to createCard

**php**

docs(api): document card limit restrictions in cards issue method

**python**

docs(api): document card limit behavior in cards create method

**ruby**

docs(api): add card limit documentation to cards create method

**typescript**

docs(api): document card limit behavior in cards issue method


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

<details>
<summary>✅ <b>grid-typescript</b> <a href="https://app.stainless.com/lightspark/grid/studio?language=typescript&branch=preview%2Fdp%2Fcard-limit-reached-error-code">studio</a> · <a href="https://github.com/stainless-sdks/grid-typescript/tree/preview%2Fdp%2Fcard-limit-reached-error-code">code</a> · <a href="https://github.com/stainless-sdks/grid-typescript/compare/preview%2Fbase%2Fdp%2Fcard-limit-reached-error-code..preview%2Fdp%2Fcard-limit-reached-error-code">diff</a></summary>

<blockquote>

<i>Your SDK build had at least one "note" diagnostic, but this did not represent a regression.</i>
<code>generate ✅</code> → <a href="https://github.com/stainless-sdks/grid-typescript/actions/runs/33697906937/job/100470692783"><code>build ✅</code></a> → <a href="https://github.com/stainless-sdks/grid-typescript/actions/runs/33697906937/job/100470692610"><code>lint ❗</code></a> → <a href="https://github.com/stainless-sdks/grid-typescript/actions/runs/33697906937/job/100470692890"><code>test ✅</code></a>
```bash
npm install https://pkg.stainless.com/s/grid-typescript/1b24aee4a7bc79ea6f20a8f2ad9027b9ef76e3ec/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-cli studio

✅ 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-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@40767988eac73fce84361637a49d40259aef30e0

✅ 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/ca6c839af8223f9b7abc3a6f6ca72f3b203fafee/grid-0.0.1-py3-none-any.whl

✅ grid-php studio · code · diff

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

⏳ These are partial results; builds are still running.

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-09-03 00:08:56 UTC

mintlify · 2026-09-03T00:00:27Z

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

Project	Status	Preview	Updated (UTC)
Grid	🟢 Ready	View Preview	Sep 3, 2026, 12:02 AM

greptile-apps · 2026-09-03T01:25:33Z

Greptile Summary

This PR extends the 409 error vocabulary with CARD_LIMIT_REACHED and documents conflict responses for card issuance.

Adds CARD_LIMIT_REACHED to the shared Error409 schema and generated OpenAPI bundles.
Adds a 409 response to POST /cards for card-limit and idempotency conflicts.
Documents how closing a card releases capacity under the platform-wide live-card cap.

Confidence Score: 4/5

The PR appears safe to merge, with a non-blocking documentation inconsistency around the per-cardholder CARD_LIMIT_REACHED trigger.

The contract additions are resolvable and synchronized across source and generated specifications, but POST /cards documents fewer CARD_LIMIT_REACHED conditions than its referenced shared error schema.

Files Needing Attention: openapi/paths/cards/cards.yaml, openapi/components/schemas/errors/Error409.yaml

Important Files Changed

Filename	Overview
openapi/components/schemas/errors/Error409.yaml	Adds CARD_LIMIT_REACHED to the closed 409 enum and describes both platform-wide and per-cardholder limit triggers.
openapi/paths/cards/cards.yaml	Adds card-cap documentation and a 409 response, but omits the per-cardholder trigger included in the referenced schema.
openapi.yaml	Correctly mirrors the modular schema and path changes in the assembled OpenAPI contract.
mintlify/openapi.yaml	Correctly mirrors the assembled OpenAPI changes for published documentation.

Prompt To Fix All With AI

### Issue 1
openapi/paths/cards/cards.yaml:90-93
**Document the per-cardholder trigger**

The shared `Error409` schema says `CARD_LIMIT_REACHED` also applies when a platform allows only one card per cardholder, but the new `POST /cards` description and 409 response mention only the platform-wide live-card cap. Integrators relying on the operation documentation therefore receive this error under an undocumented condition.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "feat(cards): add CARD_LIMIT_REACHED to t..." | Re-trigger Greptile}

greptile-apps · 2026-09-03T01:25:36Z

+        reached the maximum number of live cards it may hold, and with
+        `CONFLICT` when the `Idempotency-Key` was already used for a
+        different card request. Closing a card frees its slot; contact
+        Lightspark to raise the limit.


Document the per-cardholder trigger

The shared Error409 schema says CARD_LIMIT_REACHED also applies when a platform allows only one card per cardholder, but the new POST /cards description and 409 response mention only the platform-wide live-card cap. Integrators relying on the operation documentation therefore receive this error under an undocumented condition.

Knowledge Base Used: Cards API

Prompt To Fix With AI

This is a comment left during a code review. Path: openapi/paths/cards/cards.yaml Line: 90-93 Comment: **Document the per-cardholder trigger** The shared `Error409` schema says `CARD_LIMIT_REACHED` also applies when a platform allows only one card per cardholder, but the new `POST /cards` description and 409 response mention only the platform-wide live-card cap. Integrators relying on the operation documentation therefore receive this error under an undocumented condition. **Knowledge Base Used:** [Cards API](https://app.greptile.com/lightspark/-/custom-context/knowledge-base/lightsparkdev/grid-api/-/docs/cards-api.md) --- For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

mintlify Bot deployed to staging - mintlify September 3, 2026 00:02 View deployment

DhruvPareek marked this pull request as ready for review September 3, 2026 01:23

greptile-apps Bot reviewed Sep 3, 2026

View reviewed changes

Navigation Menu

Uh oh!

feat(cards): add CARD_LIMIT_REACHED to the 409 error vocabulary - #895

feat(cards): add CARD_LIMIT_REACHED to the 409 error vocabulary#895
DhruvPareek wants to merge 1 commit into
mainfrom
dp/card-limit-reached-error-code

DhruvPareek commented Sep 2, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Sep 2, 2026 •

edited

Loading

Uh oh!

DhruvPareek commented Sep 2, 2026

Uh oh!

github-actions Bot commented Sep 2, 2026 •

edited

Loading

Uh oh!

mintlify Bot commented Sep 3, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot commented Sep 3, 2026

Important Files Changed

Uh oh!

greptile-apps Bot Sep 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

DhruvPareek commented Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reason

Overview

Test Plan

Uh oh!

vercel Bot commented Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DhruvPareek commented Sep 2, 2026

Uh oh!

github-actions Bot commented Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✱ Stainless preview builds for grid

Uh oh!

mintlify Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

greptile-apps Bot commented Sep 3, 2026

Greptile Summary

Confidence Score: 4/5

Important Files Changed

Uh oh!

greptile-apps Bot Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

DhruvPareek commented Sep 2, 2026 •

edited

Loading

vercel Bot commented Sep 2, 2026 •

edited

Loading

github-actions Bot commented Sep 2, 2026 •

edited

Loading

mintlify Bot commented Sep 3, 2026 •

edited

Loading