Errors and limits
Errors are JSON: {"error": "…"} plus details where useful (field errors, required and available credits).
Status codes
400 | Invalid request; details.fieldErrors names the fields. |
401 | Missing, invalid or expired credentials (OAuth clients refresh and retry). |
402 | Not enough credits (required and available tell you how many), the workspace has no active plan ("code": "plan_required": uploading and making videos need one, chosen in the app), or its storage is full ("code": "storage_full": delete videos or songs, or move up a plan; GET /account has storage). |
403 | The credentials lack the scope, or the action is reserved to the app. |
404 | Not found in this workspace. |
409 | A state conflict: the song is still being analyzed, or the quote expired, was used or no longer matches. |
503 | AI video is briefly unavailable on our side ("code": "AI_VIDEO_UNAVAILABLE"): nothing was held; try again after Retry-After seconds. |
Failed videos
A failed video has error (a message to show) and error_code, and its credits are released. AI_VIDEO_UNAVAILABLE means its AI video couldn’t be made for a reason on our side, not the request’s: make it again later.
Limits
Concurrent renders are limited by your plan; extra videos wait in the queue.
A workspace is an artist's (one artist: artist_id may be left out of song uploads) or a label's (a roster). GET /account returns its type and whether its plan is active; PATCH /organization renames it or switches its type.