Limits & errors
Account and tool limits, the error format, HTTP errors and job errors, and how to handle them.
Account limits
Limits depend on the account's tier: Free until its first purchase, Pay as you go from the next request after any credit pack is bought (and after a monthly bundle ends), and Monthly bundle while one is active. GET /v1/me returns your tier in plan (free | pack | pro), your limits and your current usage.
Account
- Jobs at once
- Free3 jobs
- Pay as you go5 jobs
- Monthly bundle8 jobs
- Results kept
- Free1 day
- Pay as you go7 days
- Monthly bundle30 days
- Largest upload
- Free50 MB
- Pay as you go100 MB
- Monthly bundle100 MB
- Longest run
- Free10 min
- Pay as you go14 min 30 s
- Monthly bundle14 min 30 s
"Jobs at once" counts queued and running jobs of every tool. GPU tools run up to 5 of an account's jobs at a time; the rest wait their turn. There is no daily job limit: your credits and your jobs at once bound how much you run. Results stay for the retention of the tier the account had when the job started.
Tool limits
Each tool also has its own size limits per job, such as its largest input. The tables show the ones that depend on the tier, and the list after them the ones that are the same on every account. Each tool's page lists all of its limits.
- Largest input
- Free50 MB
- Pay as you go100 MB
- Monthly bundle100 MB
- Largest model
- Free1,000,000 faces
- Pay as you go2,000,000 faces
- Monthly bundle2,000,000 faces
- Largest input
- Free50 MB
- Pay as you go100 MB
- Monthly bundle100 MB
- Largest input
- Free50 MB
- Pay as you go100 MB
- Monthly bundle100 MB
- Most parts
- Free32
- Pay as you go64
- Monthly bundle64
- Largest model
- Free200,000 faces
- Pay as you go2,000,000 faces
- Monthly bundle2,000,000 faces
- Most pages
- Free500
- Pay as you go5,000
- Monthly bundle5,000
- Largest input
- Free20 MB
- Pay as you go100 MB
- Monthly bundle100 MB
- create_pixel_sprite
- Largest input: 20 MB
- create_3d_model_from_image
- Largest input: 20 MB
- split_3d_model
- Largest model: 200,000 faces
- get_random_numbers
- Most values per job: 1,000
- run_draw
- Most entries: 10,000
- get_random_bytes
- Most values per job: 64
Error format
Errors return JSON: {"error": {"code": "…", "message": "…"}}. Codes are stable; messages may change. Over MCP, the same code and message come back as a tool error.
HTTP errors
A request that cannot start a job, or reach one, returns an HTTP error:
- 400
invalid_request, invalid_json, invalid_options, url_not_allowedThe request is invalid; the message says what to fix.- 401
unauthorizedMissing, invalid or revoked API key.- 402
insufficient_creditsThe balance is below the required price. The message says what the job costs and what you have.- 403
invalid_token, account_disabledAn upload or download URL is invalid or expired (create a new upload, or get the job again for fresh URLs), or the account is disabled.- 404
not_found, upload_not_foundNo such job, tool or file, or the uploaded input is missing or no longer available.- 409
job_running, idempotency_conflict, already_uploadedThe job cannot be canceled in its current state, a key was reused for another tool or a different request, or an upload URL already received its file (create a new upload).- 410
job_deletedThe job an idempotency key created was deleted. Use a new key.- 411
length_requiredUploads need a Content-Length header (curl --data-binary sets it).- 413
too_largeThe file is larger than your upload limit.- 422
fetch_failedThe public URL could not be downloaded.- 429
too_many_active_jobs, rate_limitedAn account or request limit was reached. Follow the Retry-After header.- 503
busy, capacity_exhaustedbusy: the service is at capacity; wait for the Retry-After header. capacity_exhausted: the day's generation capacity is used up; try again later.
Job errors
A job that fails is still returned with 200; its error says why, with a hint when there is something to change. Every tool can return these, and each tool's page lists its own:
- unsupported_format
- The tool does not take this file type.
- insufficient_credits
- The job costs more than the balance, which is known once the input has been measured. Nothing was charged.
- timeout
- The job did not finish within its time limit.
- out_of_memory
- The file needs more memory than a job has.
Handling errors
- When a
429or503 busycarriesRetry-After, wait that long before trying once more. Don't assume an hourly reset when the header is absent, or work around a limit. - A failed job costs nothing. Read
error.hintbefore retrying: validation errors such asunsupported_format,invalid_mesh,invalid_pdforlimit_exceededfail again with the same file. 402 insufficient_credits: the message says what the job costs. Only the account's owner can add credits (Credits & prices).- After a network error, repeat the request with the same idempotency key rather than starting a new job.