Skip to content
MCPBytes
DocsLimits & errors

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.

optimize_3d_model

Largest input
Free50 MB
Pay as you go100 MB
Monthly bundle100 MB

simplify_3d_model

Largest model
Free1,000,000 faces
Pay as you go2,000,000 faces
Monthly bundle2,000,000 faces

rig_3d_model

Largest input
Free50 MB
Pay as you go100 MB
Monthly bundle100 MB

animate_3d_model

Largest input
Free50 MB
Pay as you go100 MB
Monthly bundle100 MB

split_3d_model

Most parts
Free32
Pay as you go64
Monthly bundle64

inspect_3d_model

Largest model
Free200,000 faces
Pay as you go2,000,000 faces
Monthly bundle2,000,000 faces

extract_pdf

Most pages
Free500
Pay as you go5,000
Monthly bundle5,000
Largest input
Free20 MB
Pay as you go100 MB
Monthly bundle100 MB
Every account
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:

HTTP errors
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:

Job errors
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 429 or 503 busy carries Retry-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.hint before retrying: validation errors such as unsupported_format, invalid_mesh, invalid_pdf or limit_exceeded fail 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.