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
reserveQuota → consumeCredits 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
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:
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: trueis already live on all checkout sessionsreserveQuota→consumeCreditstwo-phase flow; the quota reservation response should carry enough context to distinguish the casesreserveQuota/consumeCreditswill need to return the reason code + reset timestamp; see companion issue in edge-authRelated
agent-mcp-credit-packs— Error Reference table needs aquota_exhaustedrow