Guide

Limits & errors

Account and tool limits, the error format, HTTP errors and job errors, and how to handle them.

Account limits

Every account has the same limits. GET /v1/me returns yours and your current usage.

Account

At a time: 1 job
Uploads: Up to 50 MB
Results: 24 hours by default

Tool limits

Each tool adds its own. Its page has them with the account limits that apply to it.

Until an account first buys credits, each tool also allows fewer jobs per day. Reaching that limit returns 429 quota_exceeded with a message that says a purchase lifts it; any credit pack or monthly bundle does, from the next request.

Tools

create_3d_model: Jobs: 20 per rolling 24 hours; 3 until your first credit purchase · Description: Up to 4,000 characters
create_image: Jobs: 20 per rolling 24 hours; 3 until your first credit purchase · Prompt: Up to 4,000 characters
create_3d_model_from_image: Jobs: 20 per rolling 24 hours; 3 until your first credit purchase · Image: Up to 20 MB and 25 megapixels
optimize_3d_model: Jobs: 20 per rolling 24 hours; 3 until your first credit purchase · Model: Up to 50 MB and 2,000,000 triangles
simplify_3d_model: Geometry: Up to 1,000,000 faces per model
split_3d_model: Model size: Up to 200,000 faces
inspect_3d_model: Inspection geometry: Up to 200,000 faces per model
extract_pdf: PDF size: Up to 500 pages and 20 MB
get_random_numbers: Numbers: 1–1,000 per job
get_random_bytes: Bytes: 1–64 per request · Results: Encrypted: 5 minutes · Local: owner-managed

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: quota_exceeded, 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

429 and 503 busy carry a Retry-After header: wait that long, then try once more. Don't 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.