Errors and limits

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

Error shape

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "insufficient credits",
    "request_id": "req_...",
    "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 pending 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

Every create request must send a unique Idempotency-Key header. Retry an uncertain create with the same key and identical payload. A reused key with a different payload is rejected as a conflict.