Errors and limits

API responses use a stable envelope so clients can distinguish transport failures from business errors.

Error shape

{
  "code": "INSUFFICIENT_CREDITS",
  "message": "insufficient credits",
  "details": {}
}

User-facing pages should show simple failure messages. Admin pages and logs can keep detailed worker, provider, and object storage errors.

Incomplete task cap

API users can be limited by the number of incomplete tasks in a rolling window. Incomplete tasks include queued and running tasks. This protects the queue without adding a strict QPS limit.

Capacity behavior

When GPU capacity is tight, the platform should accept eligible tasks into the queue and expose queue status. Hard safety limits still protect the database, queue, object storage, and GPU scheduler.

Idempotency

Create requests should use an idempotency key when clients retry after network failures. A reused key with a different payload is rejected as a conflict.