Errors & rate limits

Status codes

Status	Meaning	What to do
400	Missing/invalid projectId or prompt.	Fix the request; do not retry as-is.
401	Missing, invalid, revoked, or disabled key (reason says which).	Check the key in the lab; create a new one if revoked.
403	The key's user has no access to the project.	Use a projectId created by the same user as the key.
429	A per-key limit was hit.	Back off; see below.
503	Engine container still starting, or key validation temporarily unavailable.	Retry - see cold starts below.

Error bodies are JSON with an error message and, where relevant, a machine-readable reason.

429 - rate limits

{ "error": "Rate limit exceeded", "reason": "limit_exceeded", "limit": "jobsPerDay" }

limit names the exceeded limit:

limit	Resets
jobsPerDay	00:00 UTC
jobsPerMonth	1st of the month, UTC
maxConcurrentJobs	As soon as one of the key's running jobs finishes
tikPerMonth	1st of the month, UTC

Limits are edited per key in the lab. Only job submissions count against quotas - status polls, event streams, and downloads are free, and a 503 rejection does not consume quota.

503 - cold starts

The first job on an idle project boots its engine container, which can take up to ~2 minutes:

{ "error": "Engine container is starting", "retryAfterSeconds": 30 }

Recommended client behavior:

1. On 503 from POST /v1/generate, wait retryAfterSeconds (default 30 s) and resubmit the same request.
2. Keep retrying up to an overall deadline of ~8 minutes.
3. Treat a 200 with a jobId as the single successful submission - rejected 503 attempts never created a job.

TIK balance

Generation spends TIK from the key owner's account (LLM usage, and AI images/audio when enabled). If the balance runs out mid-job, the job fails with a TIK error visible in the status record. The optional per-key monthly TIK budget caps how much a single key can spend.