Business Rules

Billing and operations rules

These rules keep API keys, credits, tasks, provider routing, and retention predictable as the model catalog grows.

API keys

Keys are shown once, hashed at rest, and may be scoped by project budget, RPM, model allowlist, and content logging.

Credits

Credits are integer units where 1 credit equals $0.001. Consumption uses the credit ledger, and manual changes require an auditable reason.

Synchronous calls

Chat calls precheck balance and budget, dispatch upstream, then charge actual or estimated usage only after a successful response.

Async media tasks

Image, video, and audio tasks reserve credits at creation, move through pending and processing states, complete with results, or fail with refunds.

Provider routing

Eligible channels are selected from model channel groups and ordered by priority, weight, health, supported type, and model fallback policy.

Callbacks

callback_url must be public HTTPS, failed deliveries retry independently, and callback failure never changes the final task status.

Retention

API detail rows keep request and response content for the configured retention window, then scheduled maintenance deletes details after monthly rollups exist.

Admin actions

Model price, channel, secret reference, user credit, and operational changes must remain traceable through durable records or admin workflows.

Customer-facing outcomes

insufficient_credits	The account cannot cover the estimated request cost, so the call is blocked before provider dispatch.
api_key_budget_exhausted	The project API key reached its configured credit budget; failed media task refunds release the budget they reserved.
rate_limit_exceeded	The API key exceeded its configured per-minute request limit and should retry after the reset time.
service_unavailable	No eligible upstream channel completed the request after allowed fallback attempts.
task failed	The task endpoint reports failed status with an error summary and credits refunded when the task had charged credits.