Errors & Overdraft Handling

The Attenval API returns standard HTTP status codes with a structured JSON error object.

Error Response Format

Error payloads return an error object with message, type, code, and an optional param field:

{
  "error": {
    "message": "Insufficient credits. Required: 80",
    "type": "insufficient_credits",
    "code": "credit_limit_exceeded",
    "param": null
  }
}

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 reserve access.
`402`	`insufficient_credits`	Available earned balance is below the estimated request minimum.	Watch a verified spotlight in the app to earn credits.
`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 alias does not exist.	Use `attenval-auto`, `attenval-fast`, `attenval-code`, or `attenval-smart`.
`429`	`rate_limit_exceeded`	Request velocity exceeded the limit.	Wait and retry using the `Retry-After` header.
`502`	`provider_error`	The request could not be completed.	Retry the request. A 502 is a retry signal, not a routing change.
`503`	`service_unavailable`	The service is temporarily unavailable.	Retry with exponential jitter.

Credit reservation

Each request reserves credits before work starts and settles to actual use when it finishes:

1. Request arrives (credits estimated from alias and token ceiling)
        ↓
2. Wallet reserves the ceiling
   - If balance < ceiling → 402 immediately
        ↓
3. Inference runs
        ↓
4. Stream completes (actual use counted)
        ↓
5. Wallet settles exact credits used and releases the unused remainder

Guarantees

No unexpected overdraft: If the reserved amount cannot be covered, the request is rejected before work starts.
Release on failure: If the request fails before usable output, reserved credits are released back to your balance.
Earned credits only: The wallet spends earned promotional credits (30-day rolling expiry). The amount a request uses depends on the alias.

Rate limiting

If you receive 429 Too Many Requests, read the Retry-After header (seconds) and wait that long before the next request. Rate-limit signaling is Retry-After on 429 only.