Error codes

The file could not be processed. Check that it is a valid audio file.

The audio is longer than 60 minutes. Trim it or split it into several files.

The note text is longer than the allowed number of characters.

A chart document holds a heatmap whose cells repeat one pattern instead of real data. Change the content and save again.

feedback_text is longer than 4096 characters.

A text field of the file details is longer than its limit. The message names the field.

The after query value is not a whole number of milliseconds.

archived is present but not true or false.

The length of the audio could not be determined. The file may be corrupted or in an unsupported format.

audio_ids is empty, too long, or has an entry that is not a non-empty string.

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.

batch_id is neither a UUID nor an older-style batch_<digits>_<hex> id.

A required field is missing or has the wrong type, or the body is not valid JSON. The message names the field.

user_bpm must be a number from 20 to 300, or null.

The color is not null and not one of the allowed tag colors.

The columns of the view definition are not valid. error.details.field names the problem.

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.

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.

conversation_id is not a UUID.

cursor must be the next_cursor string of a previous page.

dry_run must be true or false.

client_duration_seconds is not a non-negative number.

embedding_model must be a non-empty string of at most 200 characters.

The expires_in value is not an integer within the allowed range.

expires_in_seconds is not a positive number, or is larger than the allowed maximum.

A text field of the file details is not a string (or null). The message names the field.

The bytes are not a supported audio file, whatever the declared type says. Check the file.

The declared type is not audio. Send an audio file.

A filter is unknown or has a value of the wrong type. error.details.field names the filter.

The multipart body could not be read. Check the encoding and the boundary.

Grouping by sound needs a finished sound grouping first (error.details.reason is no_grouping), or the group key is not supported.

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.

An id in the path or in the request body is not a valid UUID.

The Idempotency-Key header must be 1 to 255 visible ASCII characters.

The body is empty or is not a JPEG, PNG or WebP image.

The duplicate check items list is empty, too long, or an item is malformed. The message names the item.

job_id has characters outside letters, digits and _ . : -, or is too long.

The request body is not valid JSON, or is not a JSON object. Send a JSON object with Content-Type: application/json.

user_key_label is not a valid musical key such as A minor or C# major.

kind is not one of text, code, sheet, image or chart.

A group label must be 1 to 60 characters, with no control characters.

limit is not a whole number in the range the route allows.

max_items must be a whole number from 1 up to the library batch limit.

max_retries must be an integer between 1 and 10.

message must be a string.

metadata must be a JSON object whose keys and values are within the documented length limits.

min_score must be a number from -1 to 1.

n_clusters must be a whole number from 2 to 20.

name is not acceptable: it is not a string, or it contains a NUL character. Send plain text.

The part number is not within the session.

part_numbers is empty, too long, or contains a number outside the session.

The recipe sent in recipe failed validation. The message names the first problem; POST /v1/recipe/validate lists them all.

recipe_id is not a string in the form rec_ + four digits + _ + a name of letters, digits and underscores.

A step's parameters is not a plain object (it is an array, text, a number or null).

The body must name exactly one reference: send audio_id or reference_url, not both and not neither, as a non-empty string.

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.

sha256 is not 64 hexadecimal characters.

sort is not a known short name or a list of { key, dir } with known keys.

sort_dir must be asc or desc.

sort_key is not one of the supported sort keys.

starred is missing or not true or false.

Only status=uploading is supported when listing sessions.

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.

tags is not an array of strings.

title must be a string.

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.

versionId is not valid percent-encoding. Encode it as a URL path segment.

version_of is not the audio_id of one of your ready files.

The view id in the path is not a UUID.

webhook_url is not an https URL that resolves to a public address.

message is longer than 32000 characters.

The after query value is missing. Send a time in milliseconds since the Unix epoch.

audio_id is missing or not a string.

audio_ids is missing, empty, or not a list of strings.

The body has no audio_url. Name the audio file to analyze.

The body has no audio_urls, or the array is empty. Send between 1 and 500 audio URLs.

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.

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.)

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.

The upload has no file part. Send the audio in a part named file.

The session request has no filename. Send the name of the file.

The path has no job_id.

name is missing, blank, or not a string.

The body has no prompt. Send the message to the assistant.

The body has no recipe_id. Name the recipe to run on every file.

The path has no share id.

The session request has no valid size_bytes. Send the size of the whole file as a positive integer.

The title is missing or blank. A body that is not valid JSON is reported the same way.

The path has no view id.

A name or label is longer than the allowed number of characters. The error message states the limit for that field.

The recipe was not made by forking another, so there is nothing to compare it with.

The update changes nothing: send a name, a definition or a config.

A tag is longer than the allowed number of characters.

The title is longer than 200 characters.

More than 5000 file ids in one request. Send them in several calls.

filter_tags names more tags than the route allows.

audio_ids names more than 100 ids. Send them in several calls.

More than 2 media items were attached to one message.

More tags than the allowed number.

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.

The import source is not available. Only provider: "link" can be requested.

The simple upload takes audio only. Upload video through the presigned upload route.

The Authorization header is not in the form Bearer <key>.

The key is unknown or has been revoked. Create a new key in your dashboard.

The key does not look like a Scarleta API key. Paid keys start with scar_live_, free keys with sk_free_.

The Authorization header has the Bearer scheme but no key after it.

The request has no Authorization header. Send your API key as Authorization: Bearer <key>.

The key is valid but not allowed to use this route.

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.

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.

Sound grouping is available on paid accounts only, and this key belongs to a free account.

The request asks for something your account may not do, for example setting catalog_status on a template recipe.

The upload URL has expired, was already used, or its token is wrong. Request a new upload URL.

The part URL has expired or its token is wrong. Ask for a new URL.

A file named in the request belongs to a different account. Use files from your own library or a public URL.

No archive with this id in your account.

The archive has no part with this number (a one-time download link has no parts).

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.

No batch with this id exists for your account.

The grouping job has no group with this id.

The sound grouping job does not exist or belongs to another account.

The conversation does not exist or belongs to another account.

The file has no cover image. Set one first.

No file or version with this id exists in your account (or it is already deleted). Check the id.

At least one of the requested files is not in your library. error.details.missing lists the ids.

No import with this id in your account.

No job with this id exists for your account.

The file has no melody analysis with a MIDI export, or it is not yours.

The account has no signing secret yet, so there is nothing to revoke.

The resource does not exist, is already gone, or is not visible to your account.

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.

The recipe this fork was made from is deleted or not visible to you.

No upload session with this id in your account.

The saved view does not exist or is not yours.

No active registered webhook address with this id exists for your account.

The archive has not finished building. Read it until its status is completed, then ask for the part.

The batch already finished, so it cannot be cancelled.

Only a batch that ended with failed or cancelled items can be retried. This one is still running or fully completed.

A sound grouping of yours is already queued or running. error.details.job_id names it. Wait for it to finish.

The grouping job has not completed, so its groups cannot be named yet.

The reference file has no sound fingerprint yet. Run the embedding analysis on it first.

A file in the selection has no readable content right now. Retry later or leave it out.

This Idempotency-Key was already used with a different request. Use a new key for a different batch.

A part has the wrong size. Upload it again at the exact part size.

Some parts have not been uploaded. Upload the missing parts (the response lists them), then complete again.

No message of the conversation matches the position and guards you sent. Nothing was deleted. Read the conversation again and retry with current values.

The session already completed or was cancelled, so it cannot take parts or be completed again.

The signing secret was revoked, so none is returned and no webhook is delivered. Rotate to create a new one.

The uploaded parts add up to more than the size declared when the session started.

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.

The upload was cancelled before it could complete. Start a new session.

The account already has 5 registered webhook addresses. Delete one, then register again.

The archive is past its retention time and can no longer be downloaded. Start a new one.

The document content is longer than 1048576 characters.

The file is over the size limit of this route. Use a presigned upload or an upload session for larger files.

The cover image is larger than 4 MiB. Send a smaller image.

metadata is larger than 16384 bytes once serialized.

The part is larger than the session part size.

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).

prompt is longer than 32768 characters. Shorten it.

The recipe is larger than 102400 bytes once serialized. Shorten it.

The file does not fit in your storage. Delete files or add tokens, then retry.

webhook_url is longer than 4096 bytes.

The stored file is not a supported audio or media file.

The assembled file is not a supported audio or video file. It was removed.

The batch has more than 500 files. Split it into several batches.

More than 5000 files would be grouped. Add filters to narrow the selection.

Fewer files with a sound fingerprint match than the number of groups asked for. error.details.file_count says how many were found.

The view or filters match no file, so there is nothing to run. error.details.matched_count is 0.

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.

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.

Too many unfinished upload sessions. Finish or cancel some, then start again.

The analysis request failed unexpectedly. Retry; contact support with the request_id if it persists.

The analysis could not be started. Nothing was charged; retry.

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.)

The batch record is incomplete on our side. Contact support with the request_id.

The message could not be processed. Retry; contact support with the request_id if it persists.

The analysis service is not available. Retry shortly; contact support with the request_id if it persists.

The item could not be created. Retry; contact support with the request_id if it persists.

The item could not be deleted. Retry.

The item could not be read. Retry.

The list could not be read. Retry.

The conversation progress could not be read. Retry.

The conversation could not be marked read. Retry.

The share link could not be created. Retry; contact support with the request_id if it persists.

The job could not be read. Retry.

The share link could not be revoked. Retry.

The conversation could not be rewound. Nothing is guaranteed to have been deleted: read the conversation, then retry.

The recipe could not be saved. Retry; contact support with the request_id if it persists.

The recipe runner is not configured in this environment. It is a deployment fault; contact support with the request_id.

The batch could not be started. Nothing was charged; retry, with the same Idempotency-Key if you sent one.

The conversation could not accept a new turn right now. Retry shortly.

The decline could not be saved. Nothing was cancelled; retry.

The turn could not be started. Nothing was charged; retry.

Chat is temporarily unavailable. Retry shortly; contact support with the request_id if it persists.

The recipe run could not be started. Nothing was charged; retry.

The archive could not be started. Retry after a short wait.

Key checking is temporarily unavailable. Retry after a short wait; no usage was recorded.

Sound grouping is not available right now, or could not be started. Retry after a short wait.

Conversation tracking is temporarily unavailable. Retry shortly.

Temporary condition: ownership of the conversation could not be checked. Retry shortly.

The database is temporarily unavailable. Retry after a short wait; nothing was changed.

The duplicate check is temporarily unavailable. Retry after a short wait.

The job could not be recorded. Nothing was charged; retry.

The recipe planner timed out. Retry after a short wait.

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.

Chat is temporarily unavailable. Retry shortly; contact support with the request_id if it persists.

The audio could not be fetched or stored because a supporting service is briefly unavailable. Nothing was charged; retry after a short wait.

Storage is temporarily unavailable. Retry after a short wait.

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.

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.