Skip to content

Errors

View Markdown llms-full.txt

Errors come back as JSON with an error field. Some endpoints add extra context (status, details).

{ "error": "Insufficient credits" }

Status codes

Section titled “Status codes”
StatusMeaningExample body
400Bad request{ "error": "Unsupported format: .xyz. Allowed: glb, gltf, ..." }
400Bad ZIP layout{ "error": "Archive must contain exactly one .obj/.gltf/.usd file" }
400Invalid filename{ "error": "Invalid filename" }
400Invalid format on download{ "error": "Invalid format. Expected one of: usd, mjcf, all" }
401Missing / invalid auth{ "error": "Authentication required" } · { "error": "Invalid API key" }
402Out of credits{ "error": "Insufficient credits" }
404Not found / not your job{ "error": "Conversion job not found" }
404MJCF unavailable{ "error": "MJCF package is not available for this conversion" }
409Wrong job state{ "error": "Job not yet completed", "status": "running" }
409Source not completed for simulate{ "error": "Source job must be completed before simulation" }
413Image too big{ "error": "Image too large (max 10MB): front.jpg" }
422Missing or long composition prompt{ "error": "prompt is required and must be 2000 characters or less" }
422Missing or long robot task{ "error": "robot_task is required and must be 2000 characters or less" }
422Invalid automatic asset class{ "error": "asset_class must be auto, rigid, or articulated" }
422Invalid geometry builder{ "error": "geometry_builder must be responses or codex" }
422Invalid composition image count{ "error": "images must contain 0, 1, or 4 files" }
422Unsupported automatic class{ "error": "Automatic generation does not support deformable assets" }
422Bad image format{ "error": "Unsupported source image format for foo.tiff" }
422Cannot simulate a simulation{ "error": "Cannot simulate a simulation job" }
502Upstream pipeline unavailable{ "error": "Conversion service unavailable: ..." }
502Automated composition failed{ "error": "Automated composition failed" }
502Simulation service down{ "error": "Simulation service unavailable: ..." }

Idempotency and credits

Section titled “Idempotency and credits”
  • Prototype charges are atomic — Asset Composer deducts the configured price when generation starts.
  • Failed prototype generation or rendering auto-refunds once — an internal idempotency guard prevents duplicate refunds.
  • 401 and 400 never charge — authentication and format validation happen before billing.
  • A SimReady conformance failure has no billing effect — the free conversion completes, the asset is delivered, and the verdict is in report.validation. See SimReady Validation.
  • Automatic generation does not require an idempotency key — overlapping identical requests are coalesced server-side.

How to react

Section titled “How to react”
You see…Do this
401Check the key. Was it revoked? Has it expired? Is the prefix correct (rgyd_live_)?
402Top up at app.rigyd.com/billing. Show the user — don’t silently retry.
409 (poll)Keep polling. The job isn’t done yet.
422Surface the message — it’s a request-shape issue and the fix is on the caller side.
502 / 5xxRetry with exponential backoff. A failed paid prototype step is auto-refunded.