Errors & Overdraft Handling

The Attenval API returns standard HTTP status codes combined with structured JSON error responses modeled after OpenAI conventions.

Error Response Format

All error payloads return an error object containing message, type, code, and an optional param field:

{
  "error": {
    "message": "Your account has insufficient credits to complete this inference request.",
    "type": "insufficient_credits_error",
    "code": "insufficient_credits",
    "param": null,
    "attenval": {
      "credits_available": 12,
      "credits_required_estimated": 80,
      "recharge_url": "https://app.attenval.com/buy"
    }
  }
}

Error Code Reference

Status	Error Code	Description	Recommended Action
`401`	`invalid_api_key`	API key is missing, malformed, or has been revoked.	Verify your `Authorization: Bearer` header or generate a new key at app.attenval.com.
`402`	`insufficient_credits`	Total available balance (earned + purchased) is below estimated request minimum.	Watch a sponsored developer spotlight to earn credits, or purchase a credit pack starting at ₹49.
`403`	`credit_cap_reached`	The API key has exceeded its configured daily credit quota.	Increase the key’s daily limit in your dashboard or wait for UTC midnight reset.
`404`	`model_not_found`	The requested model alias does not exist.	Use `attenval-auto`, `attenval-fast`, `attenval-code`, or `attenval-smart`.
`429`	`rate_limit_exceeded`	Request velocity exceeded the per-minute concurrency or token rate limit.	Implement exponential backoff using the `Retry-After` header.
`502`	`upstream_provider_error`	Downstream inference provider returned an unexpected error.	Automatic failover is attempted. If this error persists, retry in 1–2 seconds.
`503`	`service_unavailable`	Edge router is temporarily experiencing degraded capacity.	Retry with exponential jitter.

Credit Reservation & Overdraft Protection

Attenval uses a two-phase reservation protocol backed by per-account SQLite Durable Objects to guarantee zero unexpected overdrafts:

1. Request Arrives (tokens estimated)
        ↓
2. Wallet DO: Reserves ceiling credits
   - If balance < ceiling → returns 402 Insufficient Credits immediately
        ↓
3. Upstream Inference Dispatched
        ↓
4. Stream Completes (actual tokens counted)
        ↓
5. Wallet DO: Settles exact credits used & releases unused remainder

Key Guarantees

Zero Negative Balances: If a request cannot be guaranteed full credit coverage for max requested tokens, it is rejected safely before consuming compute.
Provider Failure Refund: If an upstream AI provider fails midway or disconnects before first token generation, 100% of reserved credits are immediately released back to your balance.
Earned First Order of Spend: The wallet automatically consumes earned promotional credits (which have a 30-day rolling validity) before touching persistent purchased credits.

Rate Limiting Headers

Every response includes rate limit telemetry headers:

x-ratelimit-limit-requests: 60
x-ratelimit-remaining-requests: 58
x-ratelimit-reset-requests: 2s
x-ratelimit-limit-tokens: 150000
x-ratelimit-remaining-tokens: 148200

If you receive a 429 Too Many Requests status, inspect the Retry-After header (in seconds) before attempting the next request.