How ZeroGPU duration and quota are checked

Mechanism for duration validation and quota pre-checks. Useful when choosing duration values, debugging illegal duration vs quota exceeded errors, and understanding why the default 60s is pessimistic for short tasks.

For per-tier numerical thresholds (free vs Pro vs Team vs Enterprise quota minutes), the daily quota window length, runs-per-day limits, and pay-as-you-go pricing, see the ZeroGPU docs — those values change over time and are deliberately kept out of this skill.

What `duration` actually requests

Whatever value is passed to @spaces.GPU(duration=N) (or the default 60s when unspecified) becomes the requested duration the platform checks against. For xlarge, the request is doubled internally:

requested = N * 2 if size == "xlarge" else N

So @spaces.GPU(duration=60, size="xlarge") is internally a 120-second request — both for the tier-max check and the quota pre-check below.

Two distinct error modes

Two failure messages can come back from the scheduler before the call runs:

Error	Trigger	What helps
`ZeroGPU illegal duration`	`requested duration > visitor's tier per-call cap`	Lower `duration`. Sign in / upgrade tier. Waiting does not help.
`ZeroGPU quota exceeded`	`remaining quota < requested duration`, OR runs-per-day cap reached	Wait for the quota window to reset. For Pro / Team / Enterprise, pay-as-you-go credits cover the overflow.

The error wording for quota exceeded includes the explicit numbers, e.g.:

You have exceeded your Pro ZeroGPU quota
(60s requested vs. 30s left). Try again in 1:23:45.

The comparison is requested vs remaining — not actual run time vs remaining. A 10-second task left at the default 60s requests 60s of quota; once remaining < 60s the call fails even though the actual work would have fit.

Why the default 60s is pessimistic for short tasks

DEFAULT_SCHEDULE_DURATION in the spaces package is 60 seconds. So an undecorated @spaces.GPU (or @spaces.GPU() with no duration=) requests 60s of quota.

For a task that actually takes ~10 seconds:

The user's 60s quota gets reserved up front.
Once their remaining quota drops below 60s, your Space fails for them — even though they could have run many more 10s tasks if the request matched reality.
Your call also ranks lower in the queue than equivalent calls declaring smaller durations.

The fix is to declare the realistic duration explicitly:

@spaces.GPU(duration=15)
def fast_task(...):
    ...

For workloads where runtime depends on inputs, use a callable (per-request estimator):

def estimate_duration(prompt, steps):
    return int(steps * 3.5)

@spaces.GPU(duration=estimate_duration)
def variable_task(prompt, steps):
    ...

This preserves quota for light inputs and reserves more only when needed.

Quota window: 24h fixed from first use

The quota window's TTL is set when the first call of a fresh window lands and counts down unconditionally — it is not a sliding window, not a calendar-day reset, and not extended by subsequent use. A user who runs a call at 14:00 sees their next reset at 14:00 the following day, regardless of how heavily or lightly they use the Space in between.

For exact tier thresholds, runs-per-day caps, and pay-as-you-go billing rates, see the ZeroGPU docs.

Queue priority

The queue is node-level — requests from every Space scheduled on the same physical node compete for that node's GPU slots. Among queued requests, shorter declared duration ranks higher. So tight per-request duration estimates serve two goals at once: they preserve the user's quota and move the request up the queue.

3.8 KiB Raw Blame History