Skip to content

feat(errors): disambiguate plan quota exhausted from zero credit balance in image_generate error #63

@stackbilt-admin

Description

@stackbilt-admin

Problem

When an authenticated Stackbilder subscriber exhausts their monthly plan quota and has no credit balance, they receive the same `insufficient_credits` error as an unsubscribed user with a zero balance:

```json
{
"error": {
"code": -32602,
"message": "Insufficient credits for image_generate. Purchase a credit pack at https://stackbilder.com/img-forge#credits to continue.",
"data": { "reason": "insufficient_credits", "purchase_url": "..." }
}
}
```

This is misleading. A Teams or Pro subscriber who has used their monthly allocation should know:

  • Their subscription quota is exhausted (not that they have "no credits")
  • When the quota resets
  • That buying a credit pack is an option, but upgrading isn't the right call

Desired behaviour

Distinguish the two cases in the error response:

Case A — Plan quota exhausted, zero credits:
```json
{
"error": {
"code": -32602,
"message": "Monthly image quota exhausted for your plan. Buy a credit pack to continue now, or wait for quota reset on [date].",
"data": {
"reason": "quota_exhausted",
"quota_resets_at": "",
"purchase_url": "https://stackbilder.com/img-forge#credits"
}
}
}
```

Case B — No plan quota AND zero credits (free tier fully consumed, or unsubscribed):
```json
{
"error": {
"code": -32602,
"message": "Insufficient credits for image_generate. Purchase a credit pack at https://stackbilder.com/img-forge#credits to continue.",
"data": {
"reason": "insufficient_credits",
"purchase_url": "https://stackbilder.com/img-forge#credits"
}
}
}
```

Context

  • allow_promotion_codes: true is already live on all checkout sessions
  • The gateway already has reserveQuotaconsumeCredits two-phase flow; the quota reservation response should carry enough context to distinguish the cases
  • Edge-auth's reserveQuota / consumeCredits will need to return the reason code + reset timestamp; see companion issue in edge-auth

Related

  • edge-auth: quota reason code + reset timestamp in reservation response (filed separately)
  • wiki: agent-mcp-credit-packs — Error Reference table needs a quota_exhausted row

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions