Errors, limits & retries

In short: every error has the same shape, only 429 and 503 are worth retrying, and failed requests are never billed.

error bodyjson

{ "error": { "code": "insufficient_credits", "message": "This request needs 5 credits; the workspace has 2.", "balance": 2, "needed": 5 } }

What does this status code mean?

Click a code to see what happened in plain words, whether to retry, whether you were charged, and what to do next.

402 Payment required

The workspace’s 5 free runs are used and its token balance cannot cover this request’s estimated input tokens.

Retry?: No, fix first
Billed?: No, failed requests are free
Who fixes it: Your account

What to do: Add credits or subscribe in the dashboard. Nothing was charged.

402 bodyjson

{ "error": { "code": "insufficient_credits", "message": "Your 5 free runs are used; add credits or subscribe at https://laya.studio/dashboard/billing. This request needs about 412 tokens (1 credit = 1 input token); the workspace has 20.", "balance": 20, "needed": 412, "free_runs_remaining": 0 } }

Status codes

Status	Meaning
`200`	Answered. x-credits-charged tells you what was billed (input tokens; 0 on a free run) and x-free-runs-remaining how many free runs are left.
`400`	Malformed body: invalid JSON, questions not an object, more than 32 questions, batch over 64.
`401`	Missing, malformed or revoked key (revocation propagates within 30 s).
`402`	The workspace’s 5 free runs are used and its token balance cannot cover this request’s estimated input tokens. Add credits or subscribe in the dashboard.
`413`	Body larger than 512 KB.
`422`	A question is invalid: unknown type, missing instructions, choice without criteria, too many options.
`429`	Rate limited (per key). Honour Retry-After.
`503`	Inference capacity is saturated or restarting. Retry with backoff; honour Retry-After.

Limits

Limit	Meaning
`Questions per request`	32
`Options per question`	64 (accuracy is best well below 20)
`Requests per batch`	64
`Body size`	512 KB
`State read per question`	512 tokens (english), 1,024 (multilingual, typed-decisions)
`Rate limit`	3,000 requests per 10 s per key (contact us to raise it)

Retry policy with exponential backoff

Retry 429 and 503 (and network errors) with jittered exponential backoff; never retry other 4xx errors. Watch the policy below play out, then copy the code. The small random jitter stops many clients from retrying at the same instant.

Capacity is saturated for a moment: two 503s, then success.

#1503

#2503

#3200

0s1s

t=0.00s attempt 1 → 503 · wait 0.37s (0.25·2^0 = 0.25s + 0.12s jitter)
t=0.49s attempt 2 → 503 · wait 0.57s (0.25·2^1 = 0.5s + 0.07s jitter)
t=1.18s attempt 3 → 200

Running…

Pythonpython

import random, time, requests

def decide(body, key, attempts=5):
    for i in range(attempts):
        r = requests.post("https://api.laya.studio/v1/systemone", json=body,
                          headers={"Authorization": f"Bearer {key}"}, timeout=30)
        if r.status_code not in (429, 503):
            r.raise_for_status()
            return r.json()
        wait = float(r.headers.get("retry-after", 0)) or min(8, 0.25 * 2 ** i)
        time.sleep(wait + random.random() * 0.25)
    r.raise_for_status()

Using Swiss-only mode? A 503 can also mean the Swiss pool is unavailable; see data residency.