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.

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.