Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
DhruvPareek wants to merge 1 commit into
base: main
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions mintlify/openapi.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

10 changes: 10 additions & 0 deletions openapi.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions openapi/components/schemas/errors/Error409.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ properties:
| INVALID_STATE_TRANSITION | The requested card `state` transition is not one of `ACTIVE ⇄ FROZEN` or `ACTIVE \| FROZEN → CLOSED` |
| CARD_ALREADY_CLOSED | `state: CLOSED` was requested for a card that is already `CLOSED` |
| CARD_NOT_MUTABLE | The card is `CLOSED`, so it can no longer be mutated |
| CARD_LIMIT_REACHED | The platform has reached the maximum number of live cards it may hold, or the cardholder already holds a card and the platform is limited to one per cardholder. Closing a card frees its slot; contact Lightspark to raise the limit |
| STABLECOIN_GRID_ENABLEMENT_NOT_REQUESTABLE | Grid enablement can only be requested while the stablecoin is `NOT_ENABLED` (a repeat request while already `PENDING_APPROVAL` succeeds). `ENABLING`, `ENABLED` and `DISABLED` are driven by Lightspark and cannot be requested |
| CONFLICT | Generic resource-state conflict. Returned, for example, when `platformCustomerId` on a customer create call collides with an existing active customer on the same platform |
enum:
Expand All @@ -39,6 +40,7 @@ properties:
- INVALID_STATE_TRANSITION
- CARD_ALREADY_CLOSED
- CARD_NOT_MUTABLE
- CARD_LIMIT_REACHED
- STABLECOIN_GRID_ENABLEMENT_NOT_REQUESTABLE
- CONFLICT
message:
Expand Down
17 changes: 17 additions & 0 deletions openapi/paths/cards/cards.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,12 @@ post:
transactions.


A platform may be limited to a maximum number of live cards. Once that
limit is reached, further issuance is rejected with `CARD_LIMIT_REACHED`
until a card is closed or Lightspark raises the limit. Cards in `CLOSED`
state do not count toward the limit.


New cards start in `state: "PROCESSING"` while the card issuer
provisions the card. The `card.state_change` webhook fires on each state
transition, including the transition to `ACTIVE` (or to `CLOSED` with
Expand Down Expand Up @@ -78,6 +84,17 @@ post:
application/json:
schema:
$ref: ../../components/schemas/errors/Error401.yaml
'409':
description: >-
Conflict. Returned with `CARD_LIMIT_REACHED` when the platform has
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.
Comment on lines +90 to +93

@greptile-apps greptile-apps Bot Sep 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 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.

content:
application/json:
schema:
$ref: ../../components/schemas/errors/Error409.yaml
'500':
description: Internal service error
content:
Expand Down
Loading