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" }
422Conflicting fields on /generate{ "error": "Provide either a text prompt or image(s), not both" }
422Missing both prompt and images{ "error": "Provide a text prompt or at least one image" }
422Prompt too long{ "error": "Prompt must be 500 characters or less" }
422Too many images{ "error": "Maximum 4 images are supported" }
422Bad image format{ "error": "Unsupported image format: foo.tiff" }
422Cannot simulate a simulation{ "error": "Cannot simulate a simulation job" }
502Upstream pipeline unavailable{ "error": "Conversion service unavailable: ..." }
502Generation service down{ "error": "Generation service unavailable: ..." }
502Simulation service down{ "error": "Simulation service unavailable: ..." }

Idempotency and credits

Section titled “Idempotency and credits”
  • Credit reservation is atomic — a 202 Accepted means the credit is held, not yet spent.
  • Failed jobs auto-refund — there’s an internal refund_applied_at guard so retries don’t double-refund.
  • 401 and 400 never charge — the credit is only reserved after auth + format validation pass.
  • A SimReady conformance failure is not an error and is not refunded — the job completes, the asset is delivered, and the verdict is in report.validation. See SimReady Validation.

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. 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. The credit is auto-refunded if the job fails.