Errors
Error shapes and codes for the hosting and asset endpoints.
Error shapes
Hosting endpoints (/api/developer/...) return:
{
"error": {
"code": "media_path",
"message": "Move assets/Hero.PNG to assets/hero.png.",
"filename": "assets/Hero.PNG"
}
}filename, limit, remaining, changed_paths and required_scope are included when they apply. limit and remaining are numbers, and changed_paths is a list or null. Request validation failures use DRF field errors.
Asset endpoints (/api/v1/...) return:
{
"detail": "prompt: This field is required.",
"code": "invalid",
"fields": { "prompt": ["This field is required."] }
}fields appears only for validation errors.
Hosting codes
| Code | What to do |
|---|---|
missing_index, unsafe_path, excluded_file, unsupported_file, invalid_media, invalid_text | Fix the bundle. Keep browser-ready files and safe relative paths. |
media_path, noncanonical_path | Move media under assets/ and rename it to the lowercase path in the message, updating references. |
duplicate_path | Two paths are the same name in Unicode NFC, or a path is both in the ZIP and in the upload session. Keep one. |
compressed_limit, expanded_limit, entry_limit, file_limit, release_upload_limit | Reduce the size or count. limit gives the bound. |
thumbnail_limit, invalid_thumbnail | Send a valid PNG or JPEG cover within the limits. |
game_expired | The claim deadline passed. Upload the build as a new game. |
claim_required, invalid_claim, used_claim | Use the original private claim link, or the owner's account. |
invalid_connection (401) | The token is wrong, revoked or expired, or belongs to another game. Ask for a new connection. |
connection_pending (403) | The owner hasn't approved the connection yet. |
connection_expired, connection_revoked (403) | Ask for a new connection. |
login_pending (403), login_inactive (401) | Publishing with a login token that isn't approved yet, or was revoked. Have the person approve it, or import anonymously. |
key_expired (401), insufficient_scope (403) | The login token expired or lacks required_scope. Start a new login. See Agent logins. |
owner_required | Sign in as the game's current owner. |
plan_required (403) | The owner's plan doesn't include code download. Releases still work; ask what changed before you release. |
project_unavailable (404) | The game doesn't exist or was deleted. |
unsupported_project (409) | Rosebud can't read this game's files back. |
version_conflict | Reconcile local and remote changes, then send the current version. changed_paths lists what changed. |
operation_reused | Retry the original input, or use a new operation ID after reconciling. |
project_busy | Wait for Rosebud generation in the game to finish. |
busy (503) | Nothing changed. Wait Retry-After seconds, then send the same request. |
sync_unavailable (503) | This server has no file-by-file uploads or file reading. Nothing changed. Send media inside the ZIP. |
upload_retry (409) | Rosebud is still checking the game's files. Repeat the identical request while remaining keeps falling. |
invalid_upload, upload_expired, upload_mismatch, upload_missing, upload_corrupt, upload_stale, invalid_md5 | See Upload media in a session. |
update_failed | Retry the same operation and payload. |
Asset codes
| Code | Status | What to do |
|---|---|---|
invalid, invalid_input | 400 | Fix the request. detail names the field. |
missing_idempotency_key, invalid_idempotency_key | 400 | Send an Idempotency-Key of 1–128 letters, digits, ., _, : or -. |
invalid_key | 401 | The login token is wrong, not approved yet, or was disconnected. Check it with GET /api/v1/agent-logins/current/, then have the person approve it or start a new login. |
key_expired | 401 | The login wasn't used for 90 days. Start a new login. |
insufficient_scope | 403 | The login lacks required_scope. Start a new login. |
key_not_allowed | 403 | This endpoint needs a signed-in browser session, not a login token. |
insufficient_credits | 402 | The person needs more credits. Don't retry. |
unknown_model, not_found | 404 | Use a model ID from GET /api/v1/asset-models/, or a job or asset in this account. |
quote_expired | 409 | Quotes last 10 minutes. Get a new quote. |
idempotency_conflict | 409 | The key was used for a different quote. Use a new key. |
not_cancelable | 409 | The job already started. Wait for it instead. |
invalid_scope | 400 | A login asked for a scope it can't have. Ask for assets:read, assets:write or games:write. |
key_limit, login_already_approved, login_revoked | 409 | Start a new login. |
login_expired | 410 | The approval link expired. Start a new login. |
throttled | 429 | Wait Retry-After seconds, then send the same request. |
unavailable | 503 | Wait and send the same request again. |