# Scarleta API error codes

Page: https://www.scarleta.ai/docs/errors
Most error responses carry a stable `code`, a message, a `request_id` and a `docs_url` that points to the entry below. A few operations answer an older flat body, `{ "error": "<code>", "message": ... }`, with the code as a plain string and no `request_id` or `docs_url`; the Responses section of each operation shows which. Branch on the code, not the message.

| Code | HTTP status | Meaning | Operations |
| --- | --- | --- | --- |
| `audio_processing_failed` | 400 | The file could not be processed. Check that it is a valid audio file. | POST /v1/analyze, POST /v1/recipe/execute |
| `audio_too_long` | 400 | The audio is longer than 60 minutes. Trim it or split it into several files. | POST /v1/analyze, POST /v1/recipe/execute |
| `body_too_long` | 400 | The note text is longer than the allowed number of characters. | POST /v1/audio/:audioId/notes |
| `degenerate_heatmap` | 400 | A `chart` document holds a heatmap whose cells repeat one pattern instead of real data. Change the content and save again. | POST /v1/documents |
| `feedback_text_too_long` | 400 | `feedback_text` is longer than 4096 characters. | POST /v1/feedback |
| `field_too_long` | 400 | A text field of the file details is longer than its limit. The message names the field. | PATCH /v1/audio/:audioId/details |
| `invalid_after` | 400 | The `after` query value is not a whole number of milliseconds. | DELETE /v1/documents/:id |
| `invalid_archived` | 400 | `archived` is present but not `true` or `false`. | POST /v1/audio/archive |
| `invalid_audio_duration` | 400 | The length of the audio could not be determined. The file may be corrupted or in an unsupported format. | POST /v1/analyze |
| `invalid_audio_ids` | 400 | `audio_ids` is empty, too long, or has an entry that is not a non-empty string. | POST /v1/audio/archives |
| `invalid_audio_url` | 400 | An audio URL in the request is not an acceptable address: it must be a public `http` or `https` URL within the length limit, with no credentials in it. The response `details` names the field or entry. | POST /v1/batch/estimate, POST /v1/batch, POST /v1/analyze, POST /v1/chat, POST /v1/conversations, POST /v1/recipe/execute |
| `invalid_batch_id` | 400 | `batch_id` is neither a UUID nor an older-style `batch_<digits>_<hex>` id. | GET /v1/batch/:batch_id, GET /v1/batch/:batch_id/results, DELETE /v1/batch/:batch_id, POST /v1/batch/:batch_id/retry |
| `invalid_body` | 400 | A required field is missing or has the wrong type, or the body is not valid JSON. The message names the field. | POST /v1/audio/versions/add, POST /v1/audio/versions/remove |
| `invalid_bpm` | 400 | `user_bpm` must be a number from 20 to 300, or null. | PATCH /v1/audio/:audioId/details |
| `invalid_color` | 400 | The color is not null and not one of the allowed tag colors. | PUT /v1/audio/tags/color |
| `invalid_columns` | 400 | The `columns` of the view definition are not valid. `error.details.field` names the problem. | POST /v1/audio/views, PUT /v1/audio/views/:viewId |
| `invalid_config` | 400 | The body has a field the route does not know, is missing a required field, or combines fields that exclude each other. `error.details.field` names the field. | POST /v1/audio/views, PUT /v1/audio/views/:viewId, GET /v1/audio/library, POST /v1/audio/library/query, POST /v1/audio/library/batch, POST /v1/audio/library/similar, POST /v1/audio/library/cluster, PUT /v1/audio/library/cluster/:job_id/groups/:group_id |
| `invalid_content_type` | 400 | The content type is not one the upload accepts. Send `multipart/form-data` to the simple upload, or one of the audio or video types listed on the presigned upload route. | POST /v1/upload, POST /v1/audio/upload-url, PUT /v1/audio/upload/:fileId, POST /v1/audio/uploads |
| `invalid_conversation_id` | 400 | `conversation_id` is not a UUID. | POST /v1/chat |
| `invalid_cursor` | 400 | `cursor` must be the `next_cursor` string of a previous page. | POST /v1/audio/library/query |
| `invalid_dry_run` | 400 | `dry_run` must be true or false. | POST /v1/audio/library/batch |
| `invalid_duration` | 400 | `client_duration_seconds` is not a non-negative number. | POST /v1/audio/uploads, POST /v1/audio/uploads/:sessionId/complete |
| `invalid_embedding_model` | 400 | `embedding_model` must be a non-empty string of at most 200 characters. | POST /v1/audio/library/cluster |
| `invalid_expires_in` | 400 | The `expires_in` value is not an integer within the allowed range. | POST /v1/audio/:fileId/download-url |
| `invalid_expiry` | 400 | `expires_in_seconds` is not a positive number, or is larger than the allowed maximum. | POST /v1/conversations/:conversationId/shares, POST /v1/audio/:audioId/shares |
| `invalid_field` | 400 | A text field of the file details is not a string (or null). The message names the field. | PATCH /v1/audio/:audioId/details |
| `invalid_file_signature` | 400 | The bytes are not a supported audio file, whatever the declared type says. Check the file. | POST /v1/upload, PUT /v1/audio/upload/:fileId |
| `invalid_file_type` | 400 | The declared type is not audio. Send an audio file. | POST /v1/upload |
| `invalid_filter` | 400 | A filter is unknown or has a value of the wrong type. `error.details.field` names the filter. | POST /v1/audio/views, PUT /v1/audio/views/:viewId, POST /v1/audio/library/query, POST /v1/audio/library/batch, POST /v1/audio/library/cluster |
| `invalid_form_data` | 400 | The multipart body could not be read. Check the encoding and the boundary. | POST /v1/upload |
| `invalid_group` | 400 | Grouping by sound needs a finished sound grouping first (`error.details.reason` is `no_grouping`), or the group key is not supported. | POST /v1/audio/views, PUT /v1/audio/views/:viewId, GET /v1/audio/library |
| `invalid_grouping` | 400 | The files cannot be grouped or ungrouped as asked: the same file twice, a file that is already in a group, or a derived file. | POST /v1/audio/versions/add, POST /v1/audio/versions/remove |
| `invalid_id` | 400 | An id in the path or in the request body is not a valid UUID. | POST /v1/documents, GET /v1/documents/:id, DELETE /v1/documents/:id, DELETE /v1/audio/:audioId/notes/:noteId |
| `invalid_idempotency_key` | 400 | The `Idempotency-Key` header must be 1 to 255 visible ASCII characters. | POST /v1/batch |
| `invalid_image` | 400 | The body is empty or is not a JPEG, PNG or WebP image. | PUT /v1/audio/:audioId/cover |
| `invalid_items` | 400 | The duplicate check `items` list is empty, too long, or an item is malformed. The message names the item. | POST /v1/audio/duplicates/check |
| `invalid_job_id` | 400 | `job_id` has characters outside letters, digits and `_ . : -`, or is too long. | GET /v1/analyze/:job_id, POST /v1/analyze/:job_id/cancel, GET /v1/analyze/:job_id/logs, GET /v1/chat/:job_id, GET /v1/conversations/:conversation_id/live-status |
| `invalid_json` | 400 | The request body is not valid JSON, or is not a JSON object. Send a JSON object with `Content-Type: application/json`. | POST /v1/batch/estimate, POST /v1/batch, POST /v1/batch/:batch_id/retry, POST /v1/analyze, POST /v1/chat, POST /v1/conversations, POST /v1/conversations/:conversationId/shares, POST /v1/recipe/validate, POST /v1/recipe/save, POST /v1/recipe/generate, POST /v1/recipe/approve, POST /v1/recipe/cancel, POST /v1/recipe/execute, POST /v1/audio/uploads, POST /v1/audio/uploads/:sessionId/part-urls, POST /v1/audio/uploads/:sessionId/complete, POST /v1/audio/duplicates/check, POST /v1/audio/imports, POST /v1/audio/archives, POST /v1/audio/tags, POST /v1/audio/tags/selection-state, POST /v1/audio/tags/rename, POST /v1/audio/tags/merge, PUT /v1/audio/tags/color, POST /v1/audio/tags/adopt, POST /v1/audio/star, POST /v1/audio/best, POST /v1/audio/archive, POST /v1/audio/bulk-delete, POST /v1/audio/rename, POST /v1/audio/views, POST /v1/audio/views/:viewId/save, PUT /v1/audio/views/:viewId, POST /v1/audio/library/query, POST /v1/audio/library/batch, POST /v1/audio/trash/restore, POST /v1/audio/trash/delete-forever, POST /v1/audio/:audioId/shares, PATCH /v1/audio/:audioId/details, POST /v1/audio/library/similar, POST /v1/audio/library/cluster, PUT /v1/audio/library/cluster/:job_id/groups/:group_id, POST /v1/webhooks |
| `invalid_key_label` | 400 | `user_key_label` is not a valid musical key such as `A minor` or `C# major`. | PATCH /v1/audio/:audioId/details |
| `invalid_kind` | 400 | `kind` is not one of `text`, `code`, `sheet`, `image` or `chart`. | POST /v1/documents |
| `invalid_label` | 400 | A group label must be 1 to 60 characters, with no control characters. | PUT /v1/audio/library/cluster/:job_id/groups/:group_id |
| `invalid_limit` | 400 | `limit` is not a whole number in the range the route allows. | GET /v1/documents, GET /v1/audio/library, POST /v1/audio/library/query, GET /v1/audio/library/similar/:audio_id, POST /v1/audio/library/similar |
| `invalid_max_items` | 400 | `max_items` must be a whole number from 1 up to the library batch limit. | POST /v1/audio/library/batch |
| `invalid_max_retries` | 400 | `max_retries` must be an integer between 1 and 10. | POST /v1/batch/:batch_id/retry |
| `invalid_message` | 400 | `message` must be a string. | POST /v1/batch |
| `invalid_metadata` | 400 | `metadata` must be a JSON object whose keys and values are within the documented length limits. | POST /v1/batch |
| `invalid_min_score` | 400 | `min_score` must be a number from -1 to 1. | GET /v1/audio/library/similar/:audio_id, POST /v1/audio/library/similar |
| `invalid_n_clusters` | 400 | `n_clusters` must be a whole number from 2 to 20. | POST /v1/audio/library/cluster |
| `invalid_name` | 400 | `name` is not acceptable: it is not a string, or it contains a NUL character. Send plain text. | POST /v1/batch, POST /v1/audio/rename, POST /v1/audio/views, PUT /v1/audio/views/:viewId |
| `invalid_part_number` | 400 | The part number is not within the session. | PUT /v1/audio/uploads/:sessionId/parts/:n |
| `invalid_part_numbers` | 400 | `part_numbers` is empty, too long, or contains a number outside the session. | POST /v1/audio/uploads/:sessionId/part-urls |
| `invalid_recipe` | 400 | The recipe sent in `recipe` failed validation. The message names the first problem; `POST /v1/recipe/validate` lists them all. | POST /v1/recipe/execute |
| `invalid_recipe_id` | 400 | `recipe_id` is not a string in the form `rec_` + four digits + `_` + a name of letters, digits and underscores. | POST /v1/batch, POST /v1/recipe/save |
| `invalid_recipe_parameters` | 400 | A step's `parameters` is not a plain object (it is an array, text, a number or null). | POST /v1/recipe/execute |
| `invalid_reference` | 400 | The body must name exactly one reference: send `audio_id` or `reference_url`, not both and not neither, as a non-empty string. | POST /v1/audio/library/similar |
| `invalid_request` | 400 | The request body is not a valid JSON object, or a required field is missing or has the wrong type or value. The error message names the field. | POST /v1/conversations/:conversation_id/rewind, POST /v1/recipe/:recipe_id/comments, POST /v1/recipe/validate, POST /v1/recipe/save, POST /v1/recipe/generate, POST /v1/recipe/approve, POST /v1/recipe/cancel, POST /v1/recipe/execute, POST /v1/feedback |
| `invalid_sha256` | 400 | `sha256` is not 64 hexadecimal characters. | POST /v1/audio/uploads, POST /v1/audio/duplicates/check |
| `invalid_sort` | 400 | `sort` is not a known short name or a list of `{ key, dir }` with known keys. | POST /v1/audio/views, PUT /v1/audio/views/:viewId, POST /v1/audio/library/query |
| `invalid_sort_dir` | 400 | `sort_dir` must be `asc` or `desc`. | GET /v1/audio/library |
| `invalid_sort_key` | 400 | `sort_key` is not one of the supported sort keys. | GET /v1/audio/library |
| `invalid_starred` | 400 | `starred` is missing or not `true` or `false`. | POST /v1/audio/star |
| `invalid_status` | 400 | Only `status=uploading` is supported when listing sessions. | GET /v1/audio/uploads |
| `invalid_tag` | 400 | A tag name is empty, not a string, or contains a NUL character(or `from` of a merge is not a list of 1 to the allowed number of names). `error.details.field` names the field. | POST /v1/audio/tags, POST /v1/audio/tags/rename, POST /v1/audio/tags/merge, PUT /v1/audio/tags/color, POST /v1/audio/tags/adopt |
| `invalid_tags` | 400 | `tags` is not an array of strings. | POST /v1/audio/uploads, POST /v1/audio/uploads/:sessionId/complete, POST /v1/audio/imports |
| `invalid_title` | 400 | `title` must be a string. | POST /v1/conversations |
| `invalid_url` | 400 | A link in the request cannot be used: it is missing, empty, too long, not an absolute address, not `http` or `https`, or points to a private or internal address. | POST /v1/audio/imports, POST /v1/media/refresh-url |
| `invalid_version_id` | 400 | `versionId` is not valid percent-encoding. Encode it as a URL path segment. | GET /v1/audio/versions/:versionId/audio-url |
| `invalid_version_of` | 400 | `version_of` is not the `audio_id` of one of your ready files. | POST /v1/audio/uploads |
| `invalid_view_id` | 400 | The view id in the path is not a UUID. | PUT /v1/audio/views/:viewId, DELETE /v1/audio/views/:viewId |
| `invalid_webhook_url` | 400 | `webhook_url` is not an https URL that resolves to a public address. | POST /v1/batch, POST /v1/recipe/execute, POST /v1/webhooks |
| `message_too_long` | 400 | `message` is longer than 32000 characters. | POST /v1/batch |
| `missing_after` | 400 | The `after` query value is missing. Send a time in milliseconds since the Unix epoch. | DELETE /v1/documents/:id |
| `missing_audio_id` | 400 | `audio_id` is missing or not a string. | POST /v1/audio/best, POST /v1/audio/rename |
| `missing_audio_ids` | 400 | `audio_ids` is missing, empty, or not a list of strings. | POST /v1/audio/tags, POST /v1/audio/tags/selection-state, POST /v1/audio/star, POST /v1/audio/archive, POST /v1/audio/bulk-delete, POST /v1/audio/trash/restore, POST /v1/audio/trash/delete-forever |
| `missing_audio_url` | 400 | The body has no `audio_url`. Name the audio file to analyze. | POST /v1/analyze, POST /v1/conversations |
| `missing_audio_urls` | 400 | The body has no `audio_urls`, or the array is empty. Send between 1 and 500 audio URLs. | POST /v1/batch/estimate, POST /v1/batch |
| `missing_body` | 400 | The request has no usable body: it is empty or, for a JSON route, the required field is missing or blank. Upload routes take the file bytes as the body; JSON routes take a JSON object. | PUT /v1/audio/upload/:fileId, PUT /v1/audio/uploads/:sessionId/parts/:n, POST /v1/audio/:audioId/notes |
| `missing_content_length` | 400 | The upload request declares no size. Send `content_length` as a positive integer. (A part sent to the API-side part route without a `Content-Length` header is refused with HTTP 411 and this same code.) | POST /v1/audio/upload-url, PUT /v1/audio/uploads/:sessionId/parts/:n |
| `missing_conversation_id` | 400 | The request has no `conversation_id`: it is missing from the path or, on the routes that take it as a query parameter, from the query string. | GET /v1/conversations/:conversation_id, GET /v1/conversations/:conversation_id/status, GET /v1/conversations/:conversation_id/live-status, POST /v1/conversations/:conversation_id/cancel, DELETE /v1/conversations/:conversation_id, PUT /v1/conversations/:conversation_id/mark-read, POST /v1/conversations/:conversation_id/rewind, POST /v1/conversations/:conversationId/shares, GET /v1/conversations/:conversationId/shares, DELETE /v1/conversations/:conversationId/shares/:shareId, GET /v1/audio/views/by-tool-call/:toolCallId |
| `missing_file` | 400 | The upload has no `file` part. Send the audio in a part named `file`. | POST /v1/upload |
| `missing_filename` | 400 | The session request has no `filename`. Send the name of the file. | POST /v1/audio/uploads |
| `missing_job_id` | 400 | The path has no `job_id`. | GET /v1/analyze/:job_id, POST /v1/analyze/:job_id/cancel, GET /v1/analyze/:job_id/logs, GET /v1/chat/:job_id |
| `missing_name` | 400 | `name` is missing, blank, or not a string. | POST /v1/audio/rename, POST /v1/audio/views, POST /v1/audio/views/:viewId/save |
| `missing_prompt` | 400 | The body has no `prompt`. Send the message to the assistant. | POST /v1/chat |
| `missing_recipe_id` | 400 | The body has no `recipe_id`. Name the recipe to run on every file. | POST /v1/batch/estimate, POST /v1/batch, POST /v1/audio/library/batch |
| `missing_share_id` | 400 | The path has no share id. | DELETE /v1/conversations/:conversationId/shares/:shareId |
| `missing_size` | 400 | The session request has no valid `size_bytes`. Send the size of the whole file as a positive integer. | POST /v1/audio/uploads |
| `missing_title` | 400 | The `title` is missing or blank. A body that is not valid JSON is reported the same way. | POST /v1/documents |
| `missing_view_id` | 400 | The path has no view id. | PUT /v1/audio/views/:viewId, DELETE /v1/audio/views/:viewId |
| `name_too_long` | 400 | A name or label is longer than the allowed number of characters. The error message states the limit for that field. | POST /v1/batch, POST /v1/recipe/save, POST /v1/recipe/:recipe_id/fork, POST /v1/audio/rename, POST /v1/audio/views, POST /v1/audio/views/:viewId/save, PUT /v1/audio/views/:viewId |
| `not_a_fork` | 400 | The recipe was not made by forking another, so there is nothing to compare it with. | GET /v1/recipe/:recipe_id/compare |
| `nothing_to_update` | 400 | The update changes nothing: send a `name`, a `definition` or a `config`. | PUT /v1/audio/views/:viewId |
| `tag_too_long` | 400 | A tag is longer than the allowed number of characters. | POST /v1/audio/uploads, POST /v1/audio/uploads/:sessionId/complete, POST /v1/audio/imports, POST /v1/audio/tags, POST /v1/audio/tags/rename, POST /v1/audio/tags/merge, PUT /v1/audio/tags/color, POST /v1/audio/tags/adopt |
| `title_too_long` | 400 | The `title` is longer than 200 characters. | POST /v1/conversations, POST /v1/documents |
| `too_many_audio_ids` | 400 | More than 5000 file ids in one request. Send them in several calls. | POST /v1/audio/tags, POST /v1/audio/tags/selection-state, POST /v1/audio/star |
| `too_many_filter_tags` | 400 | `filter_tags` names more tags than the route allows. | GET /v1/audio/library |
| `too_many_ids` | 400 | `audio_ids` names more than 100 ids. Send them in several calls. | POST /v1/audio/archive, POST /v1/audio/bulk-delete, POST /v1/audio/trash/restore, POST /v1/audio/trash/delete-forever |
| `too_many_media` | 400 | More than 2 media items were attached to one message. | POST /v1/chat |
| `too_many_tags` | 400 | More tags than the allowed number. | POST /v1/audio/uploads, POST /v1/audio/uploads/:sessionId/complete, POST /v1/audio/imports, POST /v1/audio/tags |
| `unsupported_format` | 400 | The file could not be read as audio. `error.details.supported_formats` lists the accepted formats; if yours is one of them the file may be damaged, so export it again. | POST /v1/analyze, POST /v1/recipe/execute |
| `unsupported_provider` | 400 | The import source is not available. Only `provider: "link"` can be requested. | POST /v1/audio/imports |
| `video_not_supported_here` | 400 | The simple upload takes audio only. Upload video through the presigned upload route. | POST /v1/upload |
| `invalid_auth_format` | 401 | The Authorization header is not in the form `Bearer <key>`. | POST /v1/batch/estimate, POST /v1/batch, GET /v1/batches, GET /v1/batch/:batch_id, GET /v1/batch/:batch_id/results, DELETE /v1/batch/:batch_id, POST /v1/batch/:batch_id/retry, POST /v1/analyze, GET /v1/analyze/:job_id, POST /v1/analyze/:job_id/cancel, GET /v1/analyze/:job_id/logs, POST /v1/chat, GET /v1/chat/:job_id, POST /v1/conversations, GET /v1/conversations, GET /v1/conversations/:conversation_id, GET /v1/conversations/:conversation_id/status, GET /v1/conversations/:conversation_id/live-status, POST /v1/conversations/:conversation_id/cancel, DELETE /v1/conversations/:conversation_id, PUT /v1/conversations/:conversation_id/mark-read, POST /v1/conversations/:conversation_id/rewind, POST /v1/conversations/:conversationId/shares, GET /v1/conversations/:conversationId/shares, DELETE /v1/conversations/:conversationId/shares/:shareId, POST /v1/documents, GET /v1/documents, GET /v1/documents/:id, DELETE /v1/documents/:id, GET /v1/recipe/browse, GET /v1/recipe/:recipe_id, GET /v1/recipe/author/:author_id, GET /v1/recipe/:recipe_id/comments, POST /v1/recipe/:recipe_id/comments, POST /v1/recipe/validate, POST /v1/recipe/save, POST /v1/recipe/:recipe_id/fork, GET /v1/recipe/:recipe_id/compare, POST /v1/recipe/:recipe_id/unpublish, DELETE /v1/recipe/:recipe_id, POST /v1/recipe/generate, POST /v1/recipe/approve, POST /v1/recipe/cancel, POST /v1/recipe/execute, GET /v1/recipe/jobs/:job_id, POST /v1/upload, POST /v1/audio/upload-url, GET /v1/audio, GET /v1/audio/storage-usage, POST /v1/audio/:fileId/download-url, DELETE /v1/audio/:fileId, POST /v1/audio/uploads, GET /v1/audio/uploads, GET /v1/audio/uploads/:sessionId, POST /v1/audio/uploads/:sessionId/part-urls, POST /v1/audio/uploads/:sessionId/complete, POST /v1/audio/uploads/:sessionId/abort, POST /v1/audio/duplicates/check, POST /v1/audio/imports, GET /v1/audio/imports, GET /v1/audio/imports/:importId, POST /v1/audio/archives, POST /v1/audio/archives/takeout, GET /v1/audio/archives/:jobId, POST /v1/audio/tags, GET /v1/audio/tags, POST /v1/audio/tags/selection-state, POST /v1/audio/tags/rename, POST /v1/audio/tags/merge, PUT /v1/audio/tags/color, POST /v1/audio/tags/adopt, POST /v1/audio/star, POST /v1/audio/best, POST /v1/audio/archive, POST /v1/audio/bulk-delete, POST /v1/audio/rename, GET /v1/audio/archives/:jobId/parts/:n/url, GET /v1/audio/views, POST /v1/audio/views, GET /v1/audio/views/by-tool-call/:toolCallId, GET /v1/audio/views/:viewId, POST /v1/audio/views/:viewId/save, GET /v1/audio/views/:viewId/summary, PUT /v1/audio/views/:viewId, DELETE /v1/audio/views/:viewId, GET /v1/audio/library, POST /v1/audio/library/query, GET /v1/audio/library/builtin-counts, GET /v1/audio/library/view-counts, GET /v1/audio/library/overview, POST /v1/audio/library/batch, GET /v1/audio/ungrouped, GET /v1/audio/trash, POST /v1/audio/trash/restore, POST /v1/audio/trash/delete-forever, POST /v1/audio/trash/empty, POST /v1/audio/versions/add, POST /v1/audio/versions/remove, GET /v1/audio/versions/:versionId/audio-url, GET /v1/audio/:audioId/notes, POST /v1/audio/:audioId/notes, DELETE /v1/audio/:audioId/notes/:noteId, POST /v1/audio/:audioId/shares, GET /v1/audio/:audioId/shares, DELETE /v1/audio/:audioId/shares/:shareId, GET /v1/audio/:audioId/analyses, GET /v1/audio/:audioId/midi, GET /v1/audio/:audioId/details, PATCH /v1/audio/:audioId/details, PUT /v1/audio/:audioId/cover, GET /v1/audio/:audioId/cover, DELETE /v1/audio/:audioId/cover, POST /v1/feedback, POST /v1/media/refresh-url, GET /v1/audio/:fileId/children, GET /v1/audio/:fileId/conversations, GET /v1/audio/library/similar/:audio_id, POST /v1/audio/library/similar, POST /v1/audio/library/cluster, GET /v1/audio/library/cluster/latest, GET /v1/audio/library/cluster/:job_id, PUT /v1/audio/library/cluster/:job_id/groups/:group_id, GET /v1/webhooks/signing-secret, POST /v1/webhooks/signing-secret/rotate, POST /v1/webhooks/signing-secret/revoke, POST /v1/webhooks, GET /v1/webhooks, DELETE /v1/webhooks/:id |
| `invalid_key` | 401 | The key is unknown or has been revoked. Create a new key in your dashboard. | POST /v1/batch/estimate, POST /v1/batch, GET /v1/batches, GET /v1/batch/:batch_id, GET /v1/batch/:batch_id/results, DELETE /v1/batch/:batch_id, POST /v1/batch/:batch_id/retry, POST /v1/analyze, GET /v1/analyze/:job_id, POST /v1/analyze/:job_id/cancel, GET /v1/analyze/:job_id/logs, POST /v1/chat, GET /v1/chat/:job_id, POST /v1/conversations, GET /v1/conversations, GET /v1/conversations/:conversation_id, GET /v1/conversations/:conversation_id/status, GET /v1/conversations/:conversation_id/live-status, POST /v1/conversations/:conversation_id/cancel, DELETE /v1/conversations/:conversation_id, PUT /v1/conversations/:conversation_id/mark-read, POST /v1/conversations/:conversation_id/rewind, POST /v1/conversations/:conversationId/shares, GET /v1/conversations/:conversationId/shares, DELETE /v1/conversations/:conversationId/shares/:shareId, POST /v1/documents, GET /v1/documents, GET /v1/documents/:id, DELETE /v1/documents/:id, GET /v1/recipe/browse, GET /v1/recipe/:recipe_id, GET /v1/recipe/author/:author_id, GET /v1/recipe/:recipe_id/comments, POST /v1/recipe/:recipe_id/comments, POST /v1/recipe/validate, POST /v1/recipe/save, POST /v1/recipe/:recipe_id/fork, GET /v1/recipe/:recipe_id/compare, POST /v1/recipe/:recipe_id/unpublish, DELETE /v1/recipe/:recipe_id, POST /v1/recipe/generate, POST /v1/recipe/approve, POST /v1/recipe/cancel, POST /v1/recipe/execute, GET /v1/recipe/jobs/:job_id, POST /v1/upload, POST /v1/audio/upload-url, GET /v1/audio, GET /v1/audio/storage-usage, POST /v1/audio/:fileId/download-url, DELETE /v1/audio/:fileId, POST /v1/audio/uploads, GET /v1/audio/uploads, GET /v1/audio/uploads/:sessionId, POST /v1/audio/uploads/:sessionId/part-urls, POST /v1/audio/uploads/:sessionId/complete, POST /v1/audio/uploads/:sessionId/abort, POST /v1/audio/duplicates/check, POST /v1/audio/imports, GET /v1/audio/imports, GET /v1/audio/imports/:importId, POST /v1/audio/archives, POST /v1/audio/archives/takeout, GET /v1/audio/archives/:jobId, POST /v1/audio/tags, GET /v1/audio/tags, POST /v1/audio/tags/selection-state, POST /v1/audio/tags/rename, POST /v1/audio/tags/merge, PUT /v1/audio/tags/color, POST /v1/audio/tags/adopt, POST /v1/audio/star, POST /v1/audio/best, POST /v1/audio/archive, POST /v1/audio/bulk-delete, POST /v1/audio/rename, GET /v1/audio/archives/:jobId/parts/:n/url, GET /v1/audio/views, POST /v1/audio/views, GET /v1/audio/views/by-tool-call/:toolCallId, GET /v1/audio/views/:viewId, POST /v1/audio/views/:viewId/save, GET /v1/audio/views/:viewId/summary, PUT /v1/audio/views/:viewId, DELETE /v1/audio/views/:viewId, GET /v1/audio/library, POST /v1/audio/library/query, GET /v1/audio/library/builtin-counts, GET /v1/audio/library/view-counts, GET /v1/audio/library/overview, POST /v1/audio/library/batch, GET /v1/audio/ungrouped, GET /v1/audio/trash, POST /v1/audio/trash/restore, POST /v1/audio/trash/delete-forever, POST /v1/audio/trash/empty, POST /v1/audio/versions/add, POST /v1/audio/versions/remove, GET /v1/audio/versions/:versionId/audio-url, GET /v1/audio/:audioId/notes, POST /v1/audio/:audioId/notes, DELETE /v1/audio/:audioId/notes/:noteId, POST /v1/audio/:audioId/shares, GET /v1/audio/:audioId/shares, DELETE /v1/audio/:audioId/shares/:shareId, GET /v1/audio/:audioId/analyses, GET /v1/audio/:audioId/midi, GET /v1/audio/:audioId/details, PATCH /v1/audio/:audioId/details, PUT /v1/audio/:audioId/cover, GET /v1/audio/:audioId/cover, DELETE /v1/audio/:audioId/cover, POST /v1/feedback, POST /v1/media/refresh-url, GET /v1/audio/:fileId/children, GET /v1/audio/:fileId/conversations, GET /v1/audio/library/similar/:audio_id, POST /v1/audio/library/similar, POST /v1/audio/library/cluster, GET /v1/audio/library/cluster/latest, GET /v1/audio/library/cluster/:job_id, PUT /v1/audio/library/cluster/:job_id/groups/:group_id, GET /v1/webhooks/signing-secret, POST /v1/webhooks/signing-secret/rotate, POST /v1/webhooks/signing-secret/revoke, POST /v1/webhooks, GET /v1/webhooks, DELETE /v1/webhooks/:id |
| `invalid_key_format` | 401 | The key does not look like a Scarleta API key. Paid keys start with `scar_live_`, free keys with `sk_free_`. | POST /v1/batch/estimate, POST /v1/batch, GET /v1/batches, GET /v1/batch/:batch_id, GET /v1/batch/:batch_id/results, DELETE /v1/batch/:batch_id, POST /v1/batch/:batch_id/retry, POST /v1/analyze, GET /v1/analyze/:job_id, POST /v1/analyze/:job_id/cancel, GET /v1/analyze/:job_id/logs, POST /v1/chat, GET /v1/chat/:job_id, POST /v1/conversations, GET /v1/conversations, GET /v1/conversations/:conversation_id, GET /v1/conversations/:conversation_id/status, GET /v1/conversations/:conversation_id/live-status, POST /v1/conversations/:conversation_id/cancel, DELETE /v1/conversations/:conversation_id, PUT /v1/conversations/:conversation_id/mark-read, POST /v1/conversations/:conversation_id/rewind, POST /v1/conversations/:conversationId/shares, GET /v1/conversations/:conversationId/shares, DELETE /v1/conversations/:conversationId/shares/:shareId, POST /v1/documents, GET /v1/documents, GET /v1/documents/:id, DELETE /v1/documents/:id, GET /v1/recipe/browse, GET /v1/recipe/:recipe_id, GET /v1/recipe/author/:author_id, GET /v1/recipe/:recipe_id/comments, POST /v1/recipe/:recipe_id/comments, POST /v1/recipe/validate, POST /v1/recipe/save, POST /v1/recipe/:recipe_id/fork, GET /v1/recipe/:recipe_id/compare, POST /v1/recipe/:recipe_id/unpublish, DELETE /v1/recipe/:recipe_id, POST /v1/recipe/generate, POST /v1/recipe/approve, POST /v1/recipe/cancel, POST /v1/recipe/execute, GET /v1/recipe/jobs/:job_id, POST /v1/upload, POST /v1/audio/upload-url, GET /v1/audio, GET /v1/audio/storage-usage, POST /v1/audio/:fileId/download-url, DELETE /v1/audio/:fileId, POST /v1/audio/uploads, GET /v1/audio/uploads, GET /v1/audio/uploads/:sessionId, POST /v1/audio/uploads/:sessionId/part-urls, POST /v1/audio/uploads/:sessionId/complete, POST /v1/audio/uploads/:sessionId/abort, POST /v1/audio/duplicates/check, POST /v1/audio/imports, GET /v1/audio/imports, GET /v1/audio/imports/:importId, POST /v1/audio/archives, POST /v1/audio/archives/takeout, GET /v1/audio/archives/:jobId, POST /v1/audio/tags, GET /v1/audio/tags, POST /v1/audio/tags/selection-state, POST /v1/audio/tags/rename, POST /v1/audio/tags/merge, PUT /v1/audio/tags/color, POST /v1/audio/tags/adopt, POST /v1/audio/star, POST /v1/audio/best, POST /v1/audio/archive, POST /v1/audio/bulk-delete, POST /v1/audio/rename, GET /v1/audio/archives/:jobId/parts/:n/url, GET /v1/audio/views, POST /v1/audio/views, GET /v1/audio/views/by-tool-call/:toolCallId, GET /v1/audio/views/:viewId, POST /v1/audio/views/:viewId/save, GET /v1/audio/views/:viewId/summary, PUT /v1/audio/views/:viewId, DELETE /v1/audio/views/:viewId, GET /v1/audio/library, POST /v1/audio/library/query, GET /v1/audio/library/builtin-counts, GET /v1/audio/library/view-counts, GET /v1/audio/library/overview, POST /v1/audio/library/batch, GET /v1/audio/ungrouped, GET /v1/audio/trash, POST /v1/audio/trash/restore, POST /v1/audio/trash/delete-forever, POST /v1/audio/trash/empty, POST /v1/audio/versions/add, POST /v1/audio/versions/remove, GET /v1/audio/versions/:versionId/audio-url, GET /v1/audio/:audioId/notes, POST /v1/audio/:audioId/notes, DELETE /v1/audio/:audioId/notes/:noteId, POST /v1/audio/:audioId/shares, GET /v1/audio/:audioId/shares, DELETE /v1/audio/:audioId/shares/:shareId, GET /v1/audio/:audioId/analyses, GET /v1/audio/:audioId/midi, GET /v1/audio/:audioId/details, PATCH /v1/audio/:audioId/details, PUT /v1/audio/:audioId/cover, GET /v1/audio/:audioId/cover, DELETE /v1/audio/:audioId/cover, POST /v1/feedback, POST /v1/media/refresh-url, GET /v1/audio/:fileId/children, GET /v1/audio/:fileId/conversations, GET /v1/audio/library/similar/:audio_id, POST /v1/audio/library/similar, POST /v1/audio/library/cluster, GET /v1/audio/library/cluster/latest, GET /v1/audio/library/cluster/:job_id, PUT /v1/audio/library/cluster/:job_id/groups/:group_id, GET /v1/webhooks/signing-secret, POST /v1/webhooks/signing-secret/rotate, POST /v1/webhooks/signing-secret/revoke, POST /v1/webhooks, GET /v1/webhooks, DELETE /v1/webhooks/:id |
| `missing_api_key` | 401 | The Authorization header has the Bearer scheme but no key after it. | POST /v1/batch/estimate, POST /v1/batch, GET /v1/batches, GET /v1/batch/:batch_id, GET /v1/batch/:batch_id/results, DELETE /v1/batch/:batch_id, POST /v1/batch/:batch_id/retry, POST /v1/analyze, GET /v1/analyze/:job_id, POST /v1/analyze/:job_id/cancel, GET /v1/analyze/:job_id/logs, POST /v1/chat, GET /v1/chat/:job_id, POST /v1/conversations, GET /v1/conversations, GET /v1/conversations/:conversation_id, GET /v1/conversations/:conversation_id/status, GET /v1/conversations/:conversation_id/live-status, POST /v1/conversations/:conversation_id/cancel, DELETE /v1/conversations/:conversation_id, PUT /v1/conversations/:conversation_id/mark-read, POST /v1/conversations/:conversation_id/rewind, POST /v1/conversations/:conversationId/shares, GET /v1/conversations/:conversationId/shares, DELETE /v1/conversations/:conversationId/shares/:shareId, POST /v1/documents, GET /v1/documents, GET /v1/documents/:id, DELETE /v1/documents/:id, GET /v1/recipe/browse, GET /v1/recipe/:recipe_id, GET /v1/recipe/author/:author_id, GET /v1/recipe/:recipe_id/comments, POST /v1/recipe/:recipe_id/comments, POST /v1/recipe/validate, POST /v1/recipe/save, POST /v1/recipe/:recipe_id/fork, GET /v1/recipe/:recipe_id/compare, POST /v1/recipe/:recipe_id/unpublish, DELETE /v1/recipe/:recipe_id, POST /v1/recipe/generate, POST /v1/recipe/approve, POST /v1/recipe/cancel, POST /v1/recipe/execute, GET /v1/recipe/jobs/:job_id, POST /v1/upload, POST /v1/audio/upload-url, GET /v1/audio, GET /v1/audio/storage-usage, POST /v1/audio/:fileId/download-url, DELETE /v1/audio/:fileId, POST /v1/audio/uploads, GET /v1/audio/uploads, GET /v1/audio/uploads/:sessionId, POST /v1/audio/uploads/:sessionId/part-urls, POST /v1/audio/uploads/:sessionId/complete, POST /v1/audio/uploads/:sessionId/abort, POST /v1/audio/duplicates/check, POST /v1/audio/imports, GET /v1/audio/imports, GET /v1/audio/imports/:importId, POST /v1/audio/archives, POST /v1/audio/archives/takeout, GET /v1/audio/archives/:jobId, POST /v1/audio/tags, GET /v1/audio/tags, POST /v1/audio/tags/selection-state, POST /v1/audio/tags/rename, POST /v1/audio/tags/merge, PUT /v1/audio/tags/color, POST /v1/audio/tags/adopt, POST /v1/audio/star, POST /v1/audio/best, POST /v1/audio/archive, POST /v1/audio/bulk-delete, POST /v1/audio/rename, GET /v1/audio/archives/:jobId/parts/:n/url, GET /v1/audio/views, POST /v1/audio/views, GET /v1/audio/views/by-tool-call/:toolCallId, GET /v1/audio/views/:viewId, POST /v1/audio/views/:viewId/save, GET /v1/audio/views/:viewId/summary, PUT /v1/audio/views/:viewId, DELETE /v1/audio/views/:viewId, GET /v1/audio/library, POST /v1/audio/library/query, GET /v1/audio/library/builtin-counts, GET /v1/audio/library/view-counts, GET /v1/audio/library/overview, POST /v1/audio/library/batch, GET /v1/audio/ungrouped, GET /v1/audio/trash, POST /v1/audio/trash/restore, POST /v1/audio/trash/delete-forever, POST /v1/audio/trash/empty, POST /v1/audio/versions/add, POST /v1/audio/versions/remove, GET /v1/audio/versions/:versionId/audio-url, GET /v1/audio/:audioId/notes, POST /v1/audio/:audioId/notes, DELETE /v1/audio/:audioId/notes/:noteId, POST /v1/audio/:audioId/shares, GET /v1/audio/:audioId/shares, DELETE /v1/audio/:audioId/shares/:shareId, GET /v1/audio/:audioId/analyses, GET /v1/audio/:audioId/midi, GET /v1/audio/:audioId/details, PATCH /v1/audio/:audioId/details, PUT /v1/audio/:audioId/cover, GET /v1/audio/:audioId/cover, DELETE /v1/audio/:audioId/cover, POST /v1/feedback, POST /v1/media/refresh-url, GET /v1/audio/:fileId/children, GET /v1/audio/:fileId/conversations, GET /v1/audio/library/similar/:audio_id, POST /v1/audio/library/similar, POST /v1/audio/library/cluster, GET /v1/audio/library/cluster/latest, GET /v1/audio/library/cluster/:job_id, PUT /v1/audio/library/cluster/:job_id/groups/:group_id, GET /v1/webhooks/signing-secret, POST /v1/webhooks/signing-secret/rotate, POST /v1/webhooks/signing-secret/revoke, POST /v1/webhooks, GET /v1/webhooks, DELETE /v1/webhooks/:id |
| `missing_auth` | 401 | The request has no Authorization header. Send your API key as `Authorization: Bearer <key>`. | POST /v1/batch/estimate, POST /v1/batch, GET /v1/batches, GET /v1/batch/:batch_id, GET /v1/batch/:batch_id/results, DELETE /v1/batch/:batch_id, POST /v1/batch/:batch_id/retry, POST /v1/analyze, GET /v1/analyze/:job_id, POST /v1/analyze/:job_id/cancel, GET /v1/analyze/:job_id/logs, POST /v1/chat, GET /v1/chat/:job_id, POST /v1/conversations, GET /v1/conversations, GET /v1/conversations/:conversation_id, GET /v1/conversations/:conversation_id/status, GET /v1/conversations/:conversation_id/live-status, POST /v1/conversations/:conversation_id/cancel, DELETE /v1/conversations/:conversation_id, PUT /v1/conversations/:conversation_id/mark-read, POST /v1/conversations/:conversation_id/rewind, POST /v1/conversations/:conversationId/shares, GET /v1/conversations/:conversationId/shares, DELETE /v1/conversations/:conversationId/shares/:shareId, POST /v1/documents, GET /v1/documents, GET /v1/documents/:id, DELETE /v1/documents/:id, GET /v1/recipe/browse, GET /v1/recipe/:recipe_id, GET /v1/recipe/author/:author_id, GET /v1/recipe/:recipe_id/comments, POST /v1/recipe/:recipe_id/comments, POST /v1/recipe/validate, POST /v1/recipe/save, POST /v1/recipe/:recipe_id/fork, GET /v1/recipe/:recipe_id/compare, POST /v1/recipe/:recipe_id/unpublish, DELETE /v1/recipe/:recipe_id, POST /v1/recipe/generate, POST /v1/recipe/approve, POST /v1/recipe/cancel, POST /v1/recipe/execute, GET /v1/recipe/jobs/:job_id, POST /v1/upload, POST /v1/audio/upload-url, GET /v1/audio, GET /v1/audio/storage-usage, POST /v1/audio/:fileId/download-url, DELETE /v1/audio/:fileId, POST /v1/audio/uploads, GET /v1/audio/uploads, GET /v1/audio/uploads/:sessionId, POST /v1/audio/uploads/:sessionId/part-urls, POST /v1/audio/uploads/:sessionId/complete, POST /v1/audio/uploads/:sessionId/abort, POST /v1/audio/duplicates/check, POST /v1/audio/imports, GET /v1/audio/imports, GET /v1/audio/imports/:importId, POST /v1/audio/archives, POST /v1/audio/archives/takeout, GET /v1/audio/archives/:jobId, POST /v1/audio/tags, GET /v1/audio/tags, POST /v1/audio/tags/selection-state, POST /v1/audio/tags/rename, POST /v1/audio/tags/merge, PUT /v1/audio/tags/color, POST /v1/audio/tags/adopt, POST /v1/audio/star, POST /v1/audio/best, POST /v1/audio/archive, POST /v1/audio/bulk-delete, POST /v1/audio/rename, GET /v1/audio/archives/:jobId/parts/:n/url, GET /v1/audio/views, POST /v1/audio/views, GET /v1/audio/views/by-tool-call/:toolCallId, GET /v1/audio/views/:viewId, POST /v1/audio/views/:viewId/save, GET /v1/audio/views/:viewId/summary, PUT /v1/audio/views/:viewId, DELETE /v1/audio/views/:viewId, GET /v1/audio/library, POST /v1/audio/library/query, GET /v1/audio/library/builtin-counts, GET /v1/audio/library/view-counts, GET /v1/audio/library/overview, POST /v1/audio/library/batch, GET /v1/audio/ungrouped, GET /v1/audio/trash, POST /v1/audio/trash/restore, POST /v1/audio/trash/delete-forever, POST /v1/audio/trash/empty, POST /v1/audio/versions/add, POST /v1/audio/versions/remove, GET /v1/audio/versions/:versionId/audio-url, GET /v1/audio/:audioId/notes, POST /v1/audio/:audioId/notes, DELETE /v1/audio/:audioId/notes/:noteId, POST /v1/audio/:audioId/shares, GET /v1/audio/:audioId/shares, DELETE /v1/audio/:audioId/shares/:shareId, GET /v1/audio/:audioId/analyses, GET /v1/audio/:audioId/midi, GET /v1/audio/:audioId/details, PATCH /v1/audio/:audioId/details, PUT /v1/audio/:audioId/cover, GET /v1/audio/:audioId/cover, DELETE /v1/audio/:audioId/cover, POST /v1/feedback, POST /v1/media/refresh-url, GET /v1/audio/:fileId/children, GET /v1/audio/:fileId/conversations, GET /v1/audio/library/similar/:audio_id, POST /v1/audio/library/similar, POST /v1/audio/library/cluster, GET /v1/audio/library/cluster/latest, GET /v1/audio/library/cluster/:job_id, PUT /v1/audio/library/cluster/:job_id/groups/:group_id, GET /v1/webhooks/signing-secret, POST /v1/webhooks/signing-secret/rotate, POST /v1/webhooks/signing-secret/revoke, POST /v1/webhooks, GET /v1/webhooks, DELETE /v1/webhooks/:id |
| `unauthorized` | 401 | The key is valid but not allowed to use this route. | POST /v1/batch/estimate, POST /v1/batch, GET /v1/batches, GET /v1/batch/:batch_id, GET /v1/batch/:batch_id/results, DELETE /v1/batch/:batch_id, POST /v1/batch/:batch_id/retry, POST /v1/analyze, GET /v1/analyze/:job_id, POST /v1/analyze/:job_id/cancel, GET /v1/analyze/:job_id/logs, POST /v1/chat, GET /v1/chat/:job_id, POST /v1/conversations, GET /v1/conversations, GET /v1/conversations/:conversation_id, GET /v1/conversations/:conversation_id/status, GET /v1/conversations/:conversation_id/live-status, POST /v1/conversations/:conversation_id/cancel, DELETE /v1/conversations/:conversation_id, PUT /v1/conversations/:conversation_id/mark-read, POST /v1/conversations/:conversation_id/rewind, POST /v1/conversations/:conversationId/shares, GET /v1/conversations/:conversationId/shares, DELETE /v1/conversations/:conversationId/shares/:shareId, POST /v1/documents, GET /v1/documents, GET /v1/documents/:id, DELETE /v1/documents/:id, GET /v1/recipe/browse, GET /v1/recipe/:recipe_id, GET /v1/recipe/author/:author_id, GET /v1/recipe/:recipe_id/comments, POST /v1/recipe/:recipe_id/comments, POST /v1/recipe/validate, POST /v1/recipe/save, POST /v1/recipe/:recipe_id/fork, GET /v1/recipe/:recipe_id/compare, POST /v1/recipe/:recipe_id/unpublish, DELETE /v1/recipe/:recipe_id, POST /v1/recipe/generate, POST /v1/recipe/approve, POST /v1/recipe/cancel, POST /v1/recipe/execute, GET /v1/recipe/jobs/:job_id, POST /v1/upload, POST /v1/audio/upload-url, GET /v1/audio, GET /v1/audio/storage-usage, POST /v1/audio/:fileId/download-url, DELETE /v1/audio/:fileId, POST /v1/audio/uploads, GET /v1/audio/uploads, GET /v1/audio/uploads/:sessionId, POST /v1/audio/uploads/:sessionId/part-urls, POST /v1/audio/uploads/:sessionId/complete, POST /v1/audio/uploads/:sessionId/abort, POST /v1/audio/duplicates/check, POST /v1/audio/imports, GET /v1/audio/imports, GET /v1/audio/imports/:importId, POST /v1/audio/archives, POST /v1/audio/archives/takeout, GET /v1/audio/archives/:jobId, POST /v1/audio/tags, GET /v1/audio/tags, POST /v1/audio/tags/selection-state, POST /v1/audio/tags/rename, POST /v1/audio/tags/merge, PUT /v1/audio/tags/color, POST /v1/audio/tags/adopt, POST /v1/audio/star, POST /v1/audio/best, POST /v1/audio/archive, POST /v1/audio/bulk-delete, POST /v1/audio/rename, GET /v1/audio/archives/:jobId/parts/:n/url, GET /v1/audio/views, POST /v1/audio/views, GET /v1/audio/views/by-tool-call/:toolCallId, GET /v1/audio/views/:viewId, POST /v1/audio/views/:viewId/save, GET /v1/audio/views/:viewId/summary, PUT /v1/audio/views/:viewId, DELETE /v1/audio/views/:viewId, GET /v1/audio/library, POST /v1/audio/library/query, GET /v1/audio/library/builtin-counts, GET /v1/audio/library/view-counts, GET /v1/audio/library/overview, POST /v1/audio/library/batch, GET /v1/audio/ungrouped, GET /v1/audio/trash, POST /v1/audio/trash/restore, POST /v1/audio/trash/delete-forever, POST /v1/audio/trash/empty, POST /v1/audio/versions/add, POST /v1/audio/versions/remove, GET /v1/audio/versions/:versionId/audio-url, GET /v1/audio/:audioId/notes, POST /v1/audio/:audioId/notes, DELETE /v1/audio/:audioId/notes/:noteId, POST /v1/audio/:audioId/shares, GET /v1/audio/:audioId/shares, DELETE /v1/audio/:audioId/shares/:shareId, GET /v1/audio/:audioId/analyses, GET /v1/audio/:audioId/midi, GET /v1/audio/:audioId/details, PATCH /v1/audio/:audioId/details, PUT /v1/audio/:audioId/cover, GET /v1/audio/:audioId/cover, DELETE /v1/audio/:audioId/cover, POST /v1/feedback, POST /v1/media/refresh-url, GET /v1/audio/:fileId/children, GET /v1/audio/:fileId/conversations, GET /v1/audio/library/similar/:audio_id, POST /v1/audio/library/similar, POST /v1/audio/library/cluster, GET /v1/audio/library/cluster/latest, GET /v1/audio/library/cluster/:job_id, PUT /v1/audio/library/cluster/:job_id/groups/:group_id, GET /v1/webhooks/signing-secret, POST /v1/webhooks/signing-secret/rotate, POST /v1/webhooks/signing-secret/revoke, POST /v1/webhooks, GET /v1/webhooks, DELETE /v1/webhooks/:id |
| `insufficient_balance` | 402 | The account has no token balance and auto-recharge is not on, or the balance cannot cover the request. Top up your tokens, then retry; nothing was charged. | POST /v1/batch, POST /v1/analyze, POST /v1/recipe/generate, POST /v1/recipe/execute, POST /v1/audio/library/batch |
| `batch_paid_only` | 403 | Batches are available on paid accounts only, and this key belongs to a free account. Upgrade the account, or call the single-file routes instead. | POST /v1/batch/estimate, POST /v1/batch, POST /v1/audio/library/batch |
| `cluster_paid_only` | 403 | Sound grouping is available on paid accounts only, and this key belongs to a free account. | POST /v1/audio/library/cluster |
| `forbidden` | 403 | The request asks for something your account may not do, for example setting `catalog_status` on a template recipe. | POST /v1/recipe/save |
| `invalid_upload_intent` | 403 | The upload URL has expired, was already used, or its token is wrong. Request a new upload URL. | PUT /v1/audio/upload/:fileId |
| `invalid_upload_token` | 403 | The part URL has expired or its token is wrong. Ask for a new URL. | PUT /v1/audio/uploads/:sessionId/parts/:n |
| `media_not_owned` | 403 | A file named in the request belongs to a different account. Use files from your own library or a public URL. | POST /v1/batch, POST /v1/analyze, POST /v1/chat, POST /v1/conversations, POST /v1/recipe/execute |
| `archive_not_found` | 404 | No archive with this id in your account. | GET /v1/audio/archives/:jobId, GET /v1/audio/archives/:jobId/parts/:n/url |
| `archive_part_not_found` | 404 | The archive has no part with this number (a one-time download link has no parts). | GET /v1/audio/archives/:jobId/parts/:n/url |
| `audio_not_found` | 404 | The audio file could not be found: a library file named in the request does not exist in your library, or the file at the audio URL could not be downloaded. | POST /v1/analyze, POST /v1/recipe/execute, POST /v1/audio/library/query, GET /v1/audio/library/similar/:audio_id, POST /v1/audio/library/similar |
| `batch_not_found` | 404 | No batch with this id exists for your account. | GET /v1/batch/:batch_id, GET /v1/batch/:batch_id/results, DELETE /v1/batch/:batch_id, POST /v1/batch/:batch_id/retry |
| `cluster_group_not_found` | 404 | The grouping job has no group with this id. | PUT /v1/audio/library/cluster/:job_id/groups/:group_id |
| `cluster_job_not_found` | 404 | The sound grouping job does not exist or belongs to another account. | POST /v1/audio/library/query, GET /v1/audio/library/cluster/latest, GET /v1/audio/library/cluster/:job_id, PUT /v1/audio/library/cluster/:job_id/groups/:group_id |
| `conversation_not_found` | 404 | The conversation does not exist or belongs to another account. | POST /v1/chat |
| `cover_not_found` | 404 | The file has no cover image. Set one first. | GET /v1/audio/:audioId/cover |
| `file_not_found` | 404 | No file or version with this id exists in your account (or it is already deleted). Check the id. | POST /v1/audio/:fileId/download-url, DELETE /v1/audio/:fileId, POST /v1/audio/versions/add, POST /v1/audio/versions/remove, GET /v1/audio/versions/:versionId/audio-url |
| `files_not_found` | 404 | At least one of the requested files is not in your library. `error.details.missing` lists the ids. | POST /v1/audio/archives |
| `import_not_found` | 404 | No import with this id in your account. | GET /v1/audio/imports/:importId |
| `job_not_found` | 404 | No job with this id exists for your account. | GET /v1/analyze/:job_id, POST /v1/analyze/:job_id/cancel, GET /v1/analyze/:job_id/logs, GET /v1/chat/:job_id |
| `midi_not_found` | 404 | The file has no melody analysis with a MIDI export, or it is not yours. | GET /v1/audio/:audioId/midi |
| `no_signing_secret` | 404 | The account has no signing secret yet, so there is nothing to revoke. | POST /v1/webhooks/signing-secret/revoke |
| `not_found` | 404 | The resource does not exist, is already gone, or is not visible to your account. | POST /v1/batch, POST /v1/batch/:batch_id/retry, GET /v1/conversations/:conversation_id, GET /v1/conversations/:conversation_id/status, GET /v1/conversations/:conversation_id/live-status, POST /v1/conversations/:conversation_id/cancel, DELETE /v1/conversations/:conversation_id, PUT /v1/conversations/:conversation_id/mark-read, POST /v1/conversations/:conversation_id/rewind, POST /v1/conversations/:conversationId/shares, DELETE /v1/conversations/:conversationId/shares/:shareId, POST /v1/documents, GET /v1/documents/:id, GET /v1/recipe/:recipe_id, GET /v1/recipe/author/:author_id, GET /v1/recipe/:recipe_id/comments, POST /v1/recipe/:recipe_id/comments, POST /v1/recipe/save, POST /v1/recipe/:recipe_id/fork, GET /v1/recipe/:recipe_id/compare, POST /v1/recipe/:recipe_id/unpublish, DELETE /v1/recipe/:recipe_id, POST /v1/recipe/generate, POST /v1/recipe/approve, POST /v1/recipe/cancel, POST /v1/recipe/execute, GET /v1/recipe/jobs/:job_id, POST /v1/audio/best, POST /v1/audio/rename, PUT /v1/audio/views/:viewId, DELETE /v1/audio/views/:viewId, POST /v1/audio/:audioId/notes, DELETE /v1/audio/:audioId/notes/:noteId, POST /v1/audio/:audioId/shares, DELETE /v1/audio/:audioId/shares/:shareId, GET /v1/audio/:audioId/analyses, GET /v1/audio/:audioId/details, PATCH /v1/audio/:audioId/details, PUT /v1/audio/:audioId/cover, GET /v1/audio/:audioId/cover, DELETE /v1/audio/:audioId/cover, POST /v1/feedback |
| `recipe_not_found` | 404 | The recipe does not exist or is not visible to your account. On a recipe cancel it also means the recipe was never proposed in that conversation. | POST /v1/batch/estimate, POST /v1/recipe/cancel, POST /v1/audio/library/batch |
| `source_not_found` | 404 | The recipe this fork was made from is deleted or not visible to you. | GET /v1/recipe/:recipe_id/compare |
| `upload_session_not_found` | 404 | No upload session with this id in your account. | GET /v1/audio/uploads/:sessionId, POST /v1/audio/uploads/:sessionId/part-urls, POST /v1/audio/uploads/:sessionId/complete, POST /v1/audio/uploads/:sessionId/abort |
| `view_not_found` | 404 | The saved view does not exist or is not yours. | GET /v1/audio/views/by-tool-call/:toolCallId, GET /v1/audio/views/:viewId, POST /v1/audio/views/:viewId/save, GET /v1/audio/views/:viewId/summary, GET /v1/audio/library, POST /v1/audio/library/batch |
| `webhook_not_found` | 404 | No active registered webhook address with this id exists for your account. | DELETE /v1/webhooks/:id |
| `archive_not_ready` | 409 | The archive has not finished building. Read it until its status is `completed`, then ask for the part. | GET /v1/audio/archives/:jobId/parts/:n/url |
| `batch_already_final` | 409 | The batch already finished, so it cannot be cancelled. | DELETE /v1/batch/:batch_id |
| `batch_not_retryable` | 409 | Only a batch that ended with failed or cancelled items can be retried. This one is still running or fully completed. | POST /v1/batch/:batch_id/retry |
| `cluster_in_progress` | 409 | A sound grouping of yours is already queued or running. `error.details.job_id` names it. Wait for it to finish. | POST /v1/audio/library/cluster |
| `cluster_job_not_ready` | 409 | The grouping job has not completed, so its groups cannot be named yet. | PUT /v1/audio/library/cluster/:job_id/groups/:group_id |
| `embedding_missing` | 409 | The reference file has no sound fingerprint yet. Run the embedding analysis on it first. | POST /v1/audio/library/query, GET /v1/audio/library/similar/:audio_id, POST /v1/audio/library/similar |
| `file_unavailable` | 409 | A file in the selection has no readable content right now. Retry later or leave it out. | POST /v1/audio/archives |
| `idempotency_key_reused` | 409 | This `Idempotency-Key` was already used with a different request. Use a new key for a different batch. | POST /v1/batch |
| `part_size_mismatch` | 409 | A part has the wrong size. Upload it again at the exact part size. | POST /v1/audio/uploads/:sessionId/complete |
| `parts_missing` | 409 | Some parts have not been uploaded. Upload the missing parts (the response lists them), then complete again. | POST /v1/audio/uploads/:sessionId/complete |
| `rewind_target_mismatch` | 409 | No message of the conversation matches the position and guards you sent. Nothing was deleted. Read the conversation again and retry with current values. | POST /v1/conversations/:conversation_id/rewind |
| `session_not_uploading` | 409 | The session already completed or was cancelled, so it cannot take parts or be completed again. | POST /v1/audio/uploads/:sessionId/part-urls, POST /v1/audio/uploads/:sessionId/complete, POST /v1/audio/uploads/:sessionId/abort, PUT /v1/audio/uploads/:sessionId/parts/:n |
| `signing_secret_revoked` | 409 | The signing secret was revoked, so none is returned and no webhook is delivered. Rotate to create a new one. | GET /v1/webhooks/signing-secret |
| `size_mismatch` | 409 | The uploaded parts add up to more than the size declared when the session started. | POST /v1/audio/uploads/:sessionId/complete |
| `turn_in_progress` | 409 | A turn is already running in this conversation. Wait until `GET /v1/conversations/{id}/status` reports no active turn, or cancel it, then send again. | POST /v1/chat, POST /v1/conversations/:conversation_id/rewind |
| `upload_reservation_missing` | 409 | The upload was cancelled before it could complete. Start a new session. | POST /v1/audio/uploads/:sessionId/complete |
| `webhook_endpoint_limit_reached` | 409 | The account already has 5 registered webhook addresses. Delete one, then register again. | POST /v1/webhooks |
| `archive_expired` | 410 | The archive is past its retention time and can no longer be downloaded. Start a new one. | GET /v1/audio/archives/:jobId/parts/:n/url |
| `content_too_large` | 413 | The document `content` is longer than 1048576 characters. | POST /v1/documents |
| `file_too_large` | 413 | The file is over the size limit of this route. Use a presigned upload or an upload session for larger files. | POST /v1/upload, POST /v1/audio/upload-url, PUT /v1/audio/upload/:fileId, POST /v1/audio/:fileId/download-url, POST /v1/audio/uploads, POST /v1/audio/uploads/:sessionId/complete |
| `image_too_large` | 413 | The cover image is larger than 4 MiB. Send a smaller image. | PUT /v1/audio/:audioId/cover |
| `metadata_too_large` | 413 | `metadata` is larger than 16384 bytes once serialized. | POST /v1/batch |
| `part_too_large` | 413 | The part is larger than the session part size. | PUT /v1/audio/uploads/:sessionId/parts/:n |
| `payload_too_large` | 413 | The request body is larger than the route accepts; the error message states the limit. Send a smaller body (for chat, a shorter message with audio attached by URL). | POST /v1/chat, PATCH /v1/audio/:audioId/details |
| `prompt_too_long` | 413 | `prompt` is longer than 32768 characters. Shorten it. | POST /v1/chat |
| `recipe_json_too_large` | 413 | The recipe is larger than 102400 bytes once serialized. Shorten it. | POST /v1/recipe/validate, POST /v1/recipe/save, POST /v1/recipe/:recipe_id/fork, POST /v1/recipe/approve, POST /v1/recipe/execute |
| `storage_quota_exceeded` | 413 | The file does not fit in your storage. Delete files or add tokens, then retry. | POST /v1/audio/upload-url, POST /v1/audio/uploads |
| `webhook_url_too_large` | 413 | `webhook_url` is longer than 4096 bytes. | POST /v1/batch, POST /v1/recipe/execute, POST /v1/webhooks |
| `invalid_audio_file` | 415 | The stored file is not a supported audio or media file. | POST /v1/audio/:fileId/download-url |
| `not_audio` | 415 | The assembled file is not a supported audio or video file. It was removed. | POST /v1/audio/uploads/:sessionId/complete |
| `batch_too_large` | 422 | The batch has more than 500 files. Split it into several batches. | POST /v1/batch/estimate, POST /v1/batch |
| `cluster_too_large` | 422 | More than 5000 files would be grouped. Add filters to narrow the selection. | POST /v1/audio/library/cluster |
| `not_enough_files` | 422 | Fewer files with a sound fingerprint match than the number of groups asked for. `error.details.file_count` says how many were found. | POST /v1/audio/library/cluster |
| `query_result_empty` | 422 | The view or filters match no file, so there is nothing to run. `error.details.matched_count` is 0. | POST /v1/audio/library/batch |
| `query_result_too_large` | 422 | More files match than `max_items` allows. Add filters or raise `max_items` up to the limit. `error.details.matched_count` says how many matched. | POST /v1/audio/library/batch |
| `rate_limit_exceeded` | 429 | Too many requests for this key or route. Wait for the number of seconds in the `Retry-After` header, then retry. The same code is returned when too many failed authentication attempts (missing, malformed or unknown keys) came from your IP address within the last hour (100 per hour); every request from that address is then refused, even with a valid key, until `Retry-After` elapses. Clients behind a shared address (office or NAT egress) can be affected by another client on it. | POST /v1/batch/estimate, POST /v1/batch, GET /v1/batches, GET /v1/batch/:batch_id, GET /v1/batch/:batch_id/results, DELETE /v1/batch/:batch_id, POST /v1/batch/:batch_id/retry, POST /v1/analyze, GET /v1/analyze/:job_id, POST /v1/analyze/:job_id/cancel, GET /v1/analyze/:job_id/logs, POST /v1/chat, GET /v1/chat/:job_id, POST /v1/conversations, GET /v1/conversations, GET /v1/conversations/:conversation_id, GET /v1/conversations/:conversation_id/status, GET /v1/conversations/:conversation_id/live-status, POST /v1/conversations/:conversation_id/cancel, DELETE /v1/conversations/:conversation_id, PUT /v1/conversations/:conversation_id/mark-read, POST /v1/conversations/:conversation_id/rewind, POST /v1/conversations/:conversationId/shares, GET /v1/conversations/:conversationId/shares, DELETE /v1/conversations/:conversationId/shares/:shareId, POST /v1/documents, GET /v1/documents, GET /v1/documents/:id, DELETE /v1/documents/:id, POST /v1/mcp/rpc, GET /v1/mcp/rpc, GET /v1/recipe/browse, GET /v1/recipe/:recipe_id, GET /v1/recipe/author/:author_id, GET /v1/recipe/:recipe_id/comments, POST /v1/recipe/:recipe_id/comments, POST /v1/recipe/validate, POST /v1/recipe/save, POST /v1/recipe/:recipe_id/fork, GET /v1/recipe/:recipe_id/compare, POST /v1/recipe/:recipe_id/unpublish, DELETE /v1/recipe/:recipe_id, POST /v1/recipe/generate, POST /v1/recipe/approve, POST /v1/recipe/cancel, POST /v1/recipe/execute, GET /v1/recipe/jobs/:job_id, POST /v1/upload, POST /v1/audio/upload-url, PUT /v1/audio/upload/:fileId, GET /v1/audio, GET /v1/audio/storage-usage, POST /v1/audio/:fileId/download-url, DELETE /v1/audio/:fileId, POST /v1/audio/uploads, GET /v1/audio/uploads, GET /v1/audio/uploads/:sessionId, POST /v1/audio/uploads/:sessionId/part-urls, POST /v1/audio/uploads/:sessionId/complete, POST /v1/audio/uploads/:sessionId/abort, PUT /v1/audio/uploads/:sessionId/parts/:n, POST /v1/audio/duplicates/check, POST /v1/audio/imports, GET /v1/audio/imports, GET /v1/audio/imports/:importId, POST /v1/audio/archives, POST /v1/audio/archives/takeout, GET /v1/audio/archives/:jobId, POST /v1/audio/tags, GET /v1/audio/tags, POST /v1/audio/tags/selection-state, POST /v1/audio/tags/rename, POST /v1/audio/tags/merge, PUT /v1/audio/tags/color, POST /v1/audio/tags/adopt, POST /v1/audio/star, POST /v1/audio/best, POST /v1/audio/archive, POST /v1/audio/bulk-delete, POST /v1/audio/rename, GET /v1/audio/archives/:jobId/parts/:n/url, GET /v1/audio/views, POST /v1/audio/views, GET /v1/audio/views/by-tool-call/:toolCallId, GET /v1/audio/views/:viewId, POST /v1/audio/views/:viewId/save, GET /v1/audio/views/:viewId/summary, PUT /v1/audio/views/:viewId, DELETE /v1/audio/views/:viewId, GET /v1/audio/library, POST /v1/audio/library/query, GET /v1/audio/library/builtin-counts, GET /v1/audio/library/view-counts, GET /v1/audio/library/overview, POST /v1/audio/library/batch, GET /v1/audio/ungrouped, GET /v1/audio/trash, POST /v1/audio/trash/restore, POST /v1/audio/trash/delete-forever, POST /v1/audio/trash/empty, POST /v1/audio/versions/add, POST /v1/audio/versions/remove, GET /v1/audio/versions/:versionId/audio-url, GET /v1/audio/:audioId/notes, POST /v1/audio/:audioId/notes, DELETE /v1/audio/:audioId/notes/:noteId, POST /v1/audio/:audioId/shares, GET /v1/audio/:audioId/shares, DELETE /v1/audio/:audioId/shares/:shareId, GET /v1/audio/:audioId/analyses, GET /v1/audio/:audioId/midi, GET /v1/audio/:audioId/details, PATCH /v1/audio/:audioId/details, PUT /v1/audio/:audioId/cover, GET /v1/audio/:audioId/cover, DELETE /v1/audio/:audioId/cover, POST /v1/feedback, POST /v1/media/refresh-url, GET /v1/audio/:fileId/children, GET /v1/audio/:fileId/conversations, GET /v1/audio/library/similar/:audio_id, POST /v1/audio/library/similar, POST /v1/audio/library/cluster, GET /v1/audio/library/cluster/latest, GET /v1/audio/library/cluster/:job_id, PUT /v1/audio/library/cluster/:job_id/groups/:group_id, GET /v1/webhooks/signing-secret, POST /v1/webhooks/signing-secret/rotate, POST /v1/webhooks/signing-secret/revoke, POST /v1/webhooks, GET /v1/webhooks, DELETE /v1/webhooks/:id |
| `too_many_active_uploads` | 429 | Too many unfinished upload sessions. Finish or cancel some, then start again. | POST /v1/audio/uploads |
| `analysis_failed` | 500 | The analysis request failed unexpectedly. Retry; contact support with the `request_id` if it persists. | POST /v1/analyze |
| `analysis_service_error` | 500 | The analysis could not be started. Nothing was charged; retry. | POST /v1/analyze |
| `batch_recipe_missing` | 500 | The batch record has no recipe on our side, so it cannot be retried. Contact support with the `request_id` if you need it recovered. (A batch whose recipe was deleted answers 404 `not_found` instead.) | POST /v1/batch/:batch_id/retry |
| `batch_tenant_missing` | 500 | The batch record is incomplete on our side. Contact support with the `request_id`. | POST /v1/batch/:batch_id/retry |
| `chat_failed` | 500 | The message could not be processed. Retry; contact support with the `request_id` if it persists. | POST /v1/chat |
| `configuration_error` | 500 | The analysis service is not available. Retry shortly; contact support with the `request_id` if it persists. | POST /v1/analyze |
| `create_failed` | 500 | The item could not be created. Retry; contact support with the `request_id` if it persists. | POST /v1/conversations, POST /v1/documents |
| `delete_failed` | 500 | The item could not be deleted. Retry. | DELETE /v1/conversations/:conversation_id, DELETE /v1/documents/:id |
| `get_failed` | 500 | The item could not be read. Retry. | GET /v1/conversations/:conversation_id, GET /v1/documents/:id |
| `list_failed` | 500 | The list could not be read. Retry. | GET /v1/conversations, GET /v1/conversations/:conversationId/shares, GET /v1/documents |
| `live_status_failed` | 500 | The conversation progress could not be read. Retry. | GET /v1/conversations/:conversation_id/live-status |
| `mark_read_failed` | 500 | The conversation could not be marked read. Retry. | PUT /v1/conversations/:conversation_id/mark-read |
| `mint_failed` | 500 | The share link could not be created. Retry; contact support with the `request_id` if it persists. | POST /v1/conversations/:conversationId/shares |
| `retrieval_failed` | 500 | The job could not be read. Retry. | GET /v1/analyze/:job_id, GET /v1/chat/:job_id |
| `revoke_failed` | 500 | The share link could not be revoked. Retry. | DELETE /v1/conversations/:conversationId/shares/:shareId |
| `rewind_failed` | 500 | The conversation could not be rewound. Nothing is guaranteed to have been deleted: read the conversation, then retry. | POST /v1/conversations/:conversation_id/rewind |
| `save_failed` | 500 | The recipe could not be saved. Retry; contact support with the `request_id` if it persists. | POST /v1/recipe/save |
| `workflow_binding_missing` | 500 | The recipe runner is not configured in this environment. It is a deployment fault; contact support with the `request_id`. | POST /v1/recipe/execute |
| `workflow_create_failed` | 500 | The batch could not be started. Nothing was charged; retry, with the same `Idempotency-Key` if you sent one. | POST /v1/batch, POST /v1/batch/:batch_id/retry |
| `conversation_do_error` | 502 | The conversation could not accept a new turn right now. Retry shortly. | POST /v1/chat, GET /v1/conversations/:conversation_id/status, POST /v1/conversations/:conversation_id/cancel, POST /v1/conversations/:conversation_id/rewind |
| `decline_record_failed` | 502 | The decline could not be saved. Nothing was cancelled; retry. | POST /v1/recipe/cancel |
| `turn_workflow_create_failed` | 502 | The turn could not be started. Nothing was charged; retry. | POST /v1/chat |
| `turn_workflow_precondition_missing` | 502 | Chat is temporarily unavailable. Retry shortly; contact support with the `request_id` if it persists. | POST /v1/chat |
| `workflow_start_failed` | 502 | The recipe run could not be started. Nothing was charged; retry. | POST /v1/recipe/execute |
| `archive_unavailable` | 503 | The archive could not be started. Retry after a short wait. | POST /v1/audio/archives, POST /v1/audio/archives/takeout |
| `auth_unavailable` | 503 | Key checking is temporarily unavailable. Retry after a short wait; no usage was recorded. | POST /v1/batch/estimate, POST /v1/batch, GET /v1/batches, GET /v1/batch/:batch_id, GET /v1/batch/:batch_id/results, DELETE /v1/batch/:batch_id, POST /v1/batch/:batch_id/retry, POST /v1/analyze, GET /v1/analyze/:job_id, POST /v1/analyze/:job_id/cancel, GET /v1/analyze/:job_id/logs, POST /v1/chat, GET /v1/chat/:job_id, POST /v1/conversations, GET /v1/conversations, GET /v1/conversations/:conversation_id, GET /v1/conversations/:conversation_id/status, GET /v1/conversations/:conversation_id/live-status, POST /v1/conversations/:conversation_id/cancel, DELETE /v1/conversations/:conversation_id, PUT /v1/conversations/:conversation_id/mark-read, POST /v1/conversations/:conversation_id/rewind, POST /v1/conversations/:conversationId/shares, GET /v1/conversations/:conversationId/shares, DELETE /v1/conversations/:conversationId/shares/:shareId, POST /v1/documents, GET /v1/documents, GET /v1/documents/:id, DELETE /v1/documents/:id, GET /v1/recipe/browse, GET /v1/recipe/:recipe_id, GET /v1/recipe/author/:author_id, GET /v1/recipe/:recipe_id/comments, POST /v1/recipe/:recipe_id/comments, POST /v1/recipe/validate, POST /v1/recipe/save, POST /v1/recipe/:recipe_id/fork, GET /v1/recipe/:recipe_id/compare, POST /v1/recipe/:recipe_id/unpublish, DELETE /v1/recipe/:recipe_id, POST /v1/recipe/generate, POST /v1/recipe/approve, POST /v1/recipe/cancel, POST /v1/recipe/execute, GET /v1/recipe/jobs/:job_id, POST /v1/upload, POST /v1/audio/upload-url, GET /v1/audio, GET /v1/audio/storage-usage, POST /v1/audio/:fileId/download-url, DELETE /v1/audio/:fileId, POST /v1/audio/uploads, GET /v1/audio/uploads, GET /v1/audio/uploads/:sessionId, POST /v1/audio/uploads/:sessionId/part-urls, POST /v1/audio/uploads/:sessionId/complete, POST /v1/audio/uploads/:sessionId/abort, POST /v1/audio/duplicates/check, POST /v1/audio/imports, GET /v1/audio/imports, GET /v1/audio/imports/:importId, POST /v1/audio/archives, POST /v1/audio/archives/takeout, GET /v1/audio/archives/:jobId, POST /v1/audio/tags, GET /v1/audio/tags, POST /v1/audio/tags/selection-state, POST /v1/audio/tags/rename, POST /v1/audio/tags/merge, PUT /v1/audio/tags/color, POST /v1/audio/tags/adopt, POST /v1/audio/star, POST /v1/audio/best, POST /v1/audio/archive, POST /v1/audio/bulk-delete, POST /v1/audio/rename, GET /v1/audio/archives/:jobId/parts/:n/url, GET /v1/audio/views, POST /v1/audio/views, GET /v1/audio/views/by-tool-call/:toolCallId, GET /v1/audio/views/:viewId, POST /v1/audio/views/:viewId/save, GET /v1/audio/views/:viewId/summary, PUT /v1/audio/views/:viewId, DELETE /v1/audio/views/:viewId, GET /v1/audio/library, POST /v1/audio/library/query, GET /v1/audio/library/builtin-counts, GET /v1/audio/library/view-counts, GET /v1/audio/library/overview, POST /v1/audio/library/batch, GET /v1/audio/ungrouped, GET /v1/audio/trash, POST /v1/audio/trash/restore, POST /v1/audio/trash/delete-forever, POST /v1/audio/trash/empty, POST /v1/audio/versions/add, POST /v1/audio/versions/remove, GET /v1/audio/versions/:versionId/audio-url, GET /v1/audio/:audioId/notes, POST /v1/audio/:audioId/notes, DELETE /v1/audio/:audioId/notes/:noteId, POST /v1/audio/:audioId/shares, GET /v1/audio/:audioId/shares, DELETE /v1/audio/:audioId/shares/:shareId, GET /v1/audio/:audioId/analyses, GET /v1/audio/:audioId/midi, GET /v1/audio/:audioId/details, PATCH /v1/audio/:audioId/details, PUT /v1/audio/:audioId/cover, GET /v1/audio/:audioId/cover, DELETE /v1/audio/:audioId/cover, POST /v1/feedback, POST /v1/media/refresh-url, GET /v1/audio/:fileId/children, GET /v1/audio/:fileId/conversations, GET /v1/audio/library/similar/:audio_id, POST /v1/audio/library/similar, POST /v1/audio/library/cluster, GET /v1/audio/library/cluster/latest, GET /v1/audio/library/cluster/:job_id, PUT /v1/audio/library/cluster/:job_id/groups/:group_id, GET /v1/webhooks/signing-secret, POST /v1/webhooks/signing-secret/rotate, POST /v1/webhooks/signing-secret/revoke, POST /v1/webhooks, GET /v1/webhooks, DELETE /v1/webhooks/:id |
| `cluster_unavailable` | 503 | Sound grouping is not available right now, or could not be started. Retry after a short wait. | POST /v1/audio/library/cluster |
| `conversation_do_unbound` | 503 | Conversation tracking is temporarily unavailable. Retry shortly. | GET /v1/conversations/:conversation_id/status, POST /v1/conversations/:conversation_id/cancel, POST /v1/conversations/:conversation_id/rewind |
| `conversation_ownership_unavailable` | 503 | Temporary condition: ownership of the conversation could not be checked. Retry shortly. | POST /v1/chat |
| `db_unavailable` | 503 | The database is temporarily unavailable. Retry after a short wait; nothing was changed. | DELETE /v1/audio/:fileId, POST /v1/audio/imports, GET /v1/audio/imports, GET /v1/audio/imports/:importId, POST /v1/audio/archives, POST /v1/audio/archives/takeout, GET /v1/audio/archives/:jobId, POST /v1/audio/tags, GET /v1/audio/tags, POST /v1/audio/tags/selection-state, POST /v1/audio/tags/rename, POST /v1/audio/tags/merge, PUT /v1/audio/tags/color, POST /v1/audio/tags/adopt, POST /v1/audio/star, POST /v1/audio/best, POST /v1/audio/archive, POST /v1/audio/rename, GET /v1/audio/archives/:jobId/parts/:n/url, POST /v1/audio/views, GET /v1/audio/views/by-tool-call/:toolCallId, GET /v1/audio/views/:viewId, POST /v1/audio/views/:viewId/save, GET /v1/audio/views/:viewId/summary, PUT /v1/audio/views/:viewId, DELETE /v1/audio/views/:viewId, GET /v1/audio/library, POST /v1/audio/library/query, GET /v1/audio/library/builtin-counts, GET /v1/audio/library/view-counts, GET /v1/audio/library/overview, POST /v1/audio/library/batch, GET /v1/audio/trash, POST /v1/audio/trash/restore, POST /v1/audio/trash/delete-forever, POST /v1/audio/trash/empty, POST /v1/audio/versions/add, POST /v1/audio/versions/remove, GET /v1/audio/versions/:versionId/audio-url, GET /v1/audio/:audioId/analyses, GET /v1/audio/:audioId/midi, GET /v1/audio/:audioId/details, PATCH /v1/audio/:audioId/details, PUT /v1/audio/:audioId/cover, GET /v1/audio/:audioId/cover, DELETE /v1/audio/:audioId/cover, POST /v1/feedback, GET /v1/audio/:fileId/children, GET /v1/audio/library/similar/:audio_id, POST /v1/audio/library/similar, POST /v1/audio/library/cluster, GET /v1/audio/library/cluster/latest, GET /v1/audio/library/cluster/:job_id, PUT /v1/audio/library/cluster/:job_id/groups/:group_id |
| `duplicates_unavailable` | 503 | The duplicate check is temporarily unavailable. Retry after a short wait. | POST /v1/audio/duplicates/check |
| `persistence_failed` | 503 | The job could not be recorded. Nothing was charged; retry. | POST /v1/analyze |
| `planner_unavailable` | 503 | The recipe planner timed out. Retry after a short wait. | POST /v1/recipe/generate |
| `rate_limit_unavailable` | 503 | Request limiting is temporarily unavailable. Retry after a short wait. When the limit store fails while a request is being counted, the same code arrives with HTTP 429 and a `Retry-After` of about 30 seconds; either way the request was refused and no usage was recorded. | POST /v1/batch/estimate, POST /v1/batch, GET /v1/batches, GET /v1/batch/:batch_id, GET /v1/batch/:batch_id/results, DELETE /v1/batch/:batch_id, POST /v1/batch/:batch_id/retry, POST /v1/analyze, GET /v1/analyze/:job_id, POST /v1/analyze/:job_id/cancel, GET /v1/analyze/:job_id/logs, POST /v1/chat, GET /v1/chat/:job_id, POST /v1/conversations, GET /v1/conversations, GET /v1/conversations/:conversation_id, GET /v1/conversations/:conversation_id/status, GET /v1/conversations/:conversation_id/live-status, POST /v1/conversations/:conversation_id/cancel, DELETE /v1/conversations/:conversation_id, PUT /v1/conversations/:conversation_id/mark-read, POST /v1/conversations/:conversation_id/rewind, POST /v1/conversations/:conversationId/shares, GET /v1/conversations/:conversationId/shares, DELETE /v1/conversations/:conversationId/shares/:shareId, POST /v1/documents, GET /v1/documents, GET /v1/documents/:id, DELETE /v1/documents/:id, POST /v1/mcp/rpc, GET /v1/mcp/rpc, GET /v1/recipe/browse, GET /v1/recipe/:recipe_id, GET /v1/recipe/author/:author_id, GET /v1/recipe/:recipe_id/comments, POST /v1/recipe/:recipe_id/comments, POST /v1/recipe/validate, POST /v1/recipe/save, POST /v1/recipe/:recipe_id/fork, GET /v1/recipe/:recipe_id/compare, POST /v1/recipe/:recipe_id/unpublish, DELETE /v1/recipe/:recipe_id, POST /v1/recipe/generate, POST /v1/recipe/approve, POST /v1/recipe/cancel, POST /v1/recipe/execute, GET /v1/recipe/jobs/:job_id, POST /v1/upload, POST /v1/audio/upload-url, PUT /v1/audio/upload/:fileId, GET /v1/audio, GET /v1/audio/storage-usage, POST /v1/audio/:fileId/download-url, DELETE /v1/audio/:fileId, POST /v1/audio/uploads, GET /v1/audio/uploads, GET /v1/audio/uploads/:sessionId, POST /v1/audio/uploads/:sessionId/part-urls, POST /v1/audio/uploads/:sessionId/complete, POST /v1/audio/uploads/:sessionId/abort, PUT /v1/audio/uploads/:sessionId/parts/:n, POST /v1/audio/duplicates/check, POST /v1/audio/imports, GET /v1/audio/imports, GET /v1/audio/imports/:importId, POST /v1/audio/archives, POST /v1/audio/archives/takeout, GET /v1/audio/archives/:jobId, POST /v1/audio/tags, GET /v1/audio/tags, POST /v1/audio/tags/selection-state, POST /v1/audio/tags/rename, POST /v1/audio/tags/merge, PUT /v1/audio/tags/color, POST /v1/audio/tags/adopt, POST /v1/audio/star, POST /v1/audio/best, POST /v1/audio/archive, POST /v1/audio/bulk-delete, POST /v1/audio/rename, GET /v1/audio/archives/:jobId/parts/:n/url, GET /v1/audio/views, POST /v1/audio/views, GET /v1/audio/views/by-tool-call/:toolCallId, GET /v1/audio/views/:viewId, POST /v1/audio/views/:viewId/save, GET /v1/audio/views/:viewId/summary, PUT /v1/audio/views/:viewId, DELETE /v1/audio/views/:viewId, GET /v1/audio/library, POST /v1/audio/library/query, GET /v1/audio/library/builtin-counts, GET /v1/audio/library/view-counts, GET /v1/audio/library/overview, POST /v1/audio/library/batch, GET /v1/audio/ungrouped, GET /v1/audio/trash, POST /v1/audio/trash/restore, POST /v1/audio/trash/delete-forever, POST /v1/audio/trash/empty, POST /v1/audio/versions/add, POST /v1/audio/versions/remove, GET /v1/audio/versions/:versionId/audio-url, GET /v1/audio/:audioId/notes, POST /v1/audio/:audioId/notes, DELETE /v1/audio/:audioId/notes/:noteId, POST /v1/audio/:audioId/shares, GET /v1/audio/:audioId/shares, DELETE /v1/audio/:audioId/shares/:shareId, GET /v1/audio/:audioId/analyses, GET /v1/audio/:audioId/midi, GET /v1/audio/:audioId/details, PATCH /v1/audio/:audioId/details, PUT /v1/audio/:audioId/cover, GET /v1/audio/:audioId/cover, DELETE /v1/audio/:audioId/cover, POST /v1/feedback, POST /v1/media/refresh-url, GET /v1/audio/:fileId/children, GET /v1/audio/:fileId/conversations, GET /v1/audio/library/similar/:audio_id, POST /v1/audio/library/similar, POST /v1/audio/library/cluster, GET /v1/audio/library/cluster/latest, GET /v1/audio/library/cluster/:job_id, PUT /v1/audio/library/cluster/:job_id/groups/:group_id, GET /v1/webhooks/signing-secret, POST /v1/webhooks/signing-secret/rotate, POST /v1/webhooks/signing-secret/revoke, POST /v1/webhooks, GET /v1/webhooks, DELETE /v1/webhooks/:id |
| `service_misconfigured` | 503 | Chat is temporarily unavailable. Retry shortly; contact support with the `request_id` if it persists. | POST /v1/chat |
| `service_unavailable` | 503 | The audio could not be fetched or stored because a supporting service is briefly unavailable. Nothing was charged; retry after a short wait. | POST /v1/analyze |
| `storage_unavailable` | 503 | Storage is temporarily unavailable. Retry after a short wait. | GET /v1/audio/archives/:jobId/parts/:n/url |
| `upload_unavailable` | 503 | The database or file storage could not be reached for this request. For an upload, nothing was registered or reserved; for a details or cover change, nothing was saved. Retry after a short wait. | POST /v1/audio/upload-url, POST /v1/audio/uploads, GET /v1/audio/uploads, GET /v1/audio/uploads/:sessionId, POST /v1/audio/uploads/:sessionId/part-urls, POST /v1/audio/uploads/:sessionId/complete, POST /v1/audio/uploads/:sessionId/abort, PUT /v1/audio/uploads/:sessionId/parts/:n, PUT /v1/audio/:audioId/cover |
| `webhook_validation_unavailable` | 503 | The webhook address (`webhook_url`, or `url` when registering a webhook) could not be checked right now because name resolution is temporarily unavailable. Nothing was created or charged; retry after a short wait. | POST /v1/batch, POST /v1/recipe/execute, POST /v1/webhooks |