Error codes
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. Quote the request id when you contact support.
HTTP 400
A Google Drive import needs a non-empty
access_token(at most 4096 characters). Pick the files again.Returned by: POST /v1/audio/imports
The file could not be processed. Check that it is a valid audio file.
Returned by: POST /v1/analyze, POST /v1/recipe/execute
The audio is longer than 60 minutes. Trim it or split it into several files.
Returned by: POST /v1/analyze, POST /v1/recipe/execute
The note text is longer than the allowed number of characters.
Returned by: POST /v1/audio/{audioId}/notes
A
chartdocument holds a heatmap whose cells repeat one pattern instead of real data. Change the content and save again.Returned by: POST /v1/documents
feedback_textis longer than 4096 characters.Returned by: POST /v1/feedback
A text field of the file details is longer than its limit. The message names the field.
Returned by: PATCH /v1/audio/{audioId}/details
The
afterquery value is not a whole number of milliseconds.Returned by: DELETE /v1/documents/{id}
archivedis present but nottrueorfalse.Returned by: POST /v1/audio/archive
The length of the audio could not be determined. The file may be corrupted or in an unsupported format.
Returned by: POST /v1/analyze
audio_idsis empty, too long, or has an entry that is not a non-empty string.Returned by: POST /v1/audio/archives
An audio URL in the request is not an acceptable address: it must be a public
httporhttpsURL within the length limit, with no credentials in it. The responsedetailsnames the field or entry.Returned by: POST /v1/batch/estimate, POST /v1/batch, POST /v1/analyze, POST /v1/chat, POST /v1/conversations, POST /v1/recipe/execute
batch_idis neither a UUID nor an older-stylebatch_<digits>_<hex>id.Returned by: GET /v1/batch/{batch_id}, GET /v1/batch/{batch_id}/results, DELETE /v1/batch/{batch_id}, POST /v1/batch/{batch_id}/retry
beforeis not a valid cursor or ISO 8601 date or timestamp.Returned by: GET /v1/conversations
invalid_body
400A required field is missing or has the wrong type, or the body is not valid JSON. The message names the field.
Returned by: POST /v1/audio/versions/add, POST /v1/audio/versions/remove
invalid_bpm
400user_bpmmust be a number from 20 to 300, or null.Returned by: PATCH /v1/audio/{audioId}/details
The color is not null and not one of the allowed tag colors.
Returned by: PUT /v1/audio/tags/color
The
columnsof the view definition are not valid.error.details.fieldnames the problem.Returned by: POST /v1/audio/views, PUT /v1/audio/views/{viewId}
The body has a field the route does not know, is missing a required field, or combines fields that exclude each other.
error.details.fieldnames the field.Returned by: 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}
The content type is not one the upload accepts. Send
multipart/form-datato the simple upload, or one of the audio or video types listed on the presigned upload route.Returned by: POST /v1/upload, POST /v1/audio/upload-url, PUT /v1/audio/upload/{fileId}, POST /v1/audio/uploads
conversation_idis not a UUID.Returned by: POST /v1/chat
cursormust be thenext_cursorstring of a previous page.Returned by: POST /v1/audio/library/query
dry_runmust be true or false.Returned by: POST /v1/audio/library/batch
client_duration_secondsis not a non-negative number.Returned by: POST /v1/audio/uploads, POST /v1/audio/uploads/{sessionId}/complete
embedding_modelmust be a non-empty string of at most 200 characters.Returned by: POST /v1/audio/library/cluster
The
expires_invalue is not an integer within the allowed range.Returned by: POST /v1/audio/{fileId}/download-url
expires_in_secondsis not a positive number, or is larger than the allowed maximum.Returned by: POST /v1/conversations/{conversationId}/shares, POST /v1/audio/{audioId}/shares
A text field of the file details is not a string (or null). The message names the field.
Returned by: PATCH /v1/audio/{audioId}/details
The bytes are not a supported audio file, whatever the declared type says. Check the file.
Returned by: POST /v1/upload, PUT /v1/audio/upload/{fileId}
The declared type is not audio. Send an audio file.
Returned by: POST /v1/upload
The
fileslist is missing, empty, or has an entry that is not valid for the provider (a bad Google Drive file id, or a Dropbox link that is not an https link ondl.dropboxusercontent.com).Returned by: POST /v1/audio/imports
A filter is unknown or has a value of the wrong type.
error.details.fieldnames the filter.Returned by: POST /v1/audio/views, PUT /v1/audio/views/{viewId}, POST /v1/audio/library/query, POST /v1/audio/library/batch, POST /v1/audio/library/cluster
The multipart body could not be read. Check the encoding and the boundary.
Returned by: POST /v1/upload
invalid_from
400fromis not a real ISO 8601 date or timestamp.Returned by: GET /v1/conversations
Grouping by sound needs a finished sound grouping first (
error.details.reasonisno_grouping), or the group key is not supported.Returned by: POST /v1/audio/views, PUT /v1/audio/views/{viewId}, GET /v1/audio/library
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.
Returned by: POST /v1/audio/versions/add, POST /v1/audio/versions/remove
invalid_id
400An id in the path or in the request body is not a valid UUID.
Returned by: POST /v1/documents, GET /v1/documents/{id}, DELETE /v1/documents/{id}, DELETE /v1/audio/{audioId}/notes/{noteId}
The
Idempotency-Keyheader must be 1 to 255 visible ASCII characters.Returned by: POST /v1/batch
The body is empty or is not a JPEG, PNG or WebP image.
Returned by: PUT /v1/audio/{audioId}/cover
The duplicate check
itemslist is empty, too long, or an item is malformed. The message names the item.Returned by: POST /v1/audio/duplicates/check
job_idhas characters outside letters, digits and_ . : -, or is too long.Returned by: 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
400The request body is not valid JSON, or is not a JSON object. Send a JSON object with
Content-Type: application/json.Returned by: 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, and 35 more
user_key_labelis not a valid musical key such asA minororC# major.Returned by: PATCH /v1/audio/{audioId}/details
invalid_kind
400kindis not one oftext,code,sheet,imageorchart.Returned by: POST /v1/documents
A group label must be 1 to 60 characters, with no control characters.
Returned by: PUT /v1/audio/library/cluster/{job_id}/groups/{group_id}
limitis not a whole number in the range the route allows.Returned by: GET /v1/documents, GET /v1/audio/library, POST /v1/audio/library/query, GET /v1/audio/library/similar/{audio_id}, POST /v1/audio/library/similar
max_itemsmust be a whole number from 1 up to the library batch limit.Returned by: POST /v1/audio/library/batch
max_retriesmust be an integer between 1 and 10.Returned by: POST /v1/batch/{batch_id}/retry
messagemust be a string.Returned by: POST /v1/batch
metadatamust be a JSON object whose keys and values are within the documented length limits.Returned by: POST /v1/batch
min_scoremust be a number from -1 to 1.Returned by: GET /v1/audio/library/similar/{audio_id}, POST /v1/audio/library/similar
n_clustersmust be a whole number from 2 to 20.Returned by: POST /v1/audio/library/cluster
invalid_name
400nameis not acceptable: it is not a string, or it contains a NUL character. Send plain text.Returned by: POST /v1/batch, POST /v1/audio/rename, POST /v1/audio/views, PUT /v1/audio/views/{viewId}
The part number is not within the session.
Returned by: PUT /v1/audio/uploads/{sessionId}/parts/{n}
part_numbersis empty, too long, or contains a number outside the session.Returned by: POST /v1/audio/uploads/{sessionId}/part-urls
invalid_q
400qhas control characters, more than 10 words, or a word over 100 characters.Returned by: GET /v1/conversations
fromis afterto.Returned by: GET /v1/conversations
The recipe sent in
recipefailed validation. The message names the first problem;POST /v1/recipe/validatelists them all.Returned by: POST /v1/recipe/execute
recipe_idis not a string in the formrec_+ four digits +_+ a name of letters, digits and underscores.Returned by: POST /v1/batch, POST /v1/recipe/save
A step's
parametersis not a plain object (it is an array, text, a number or null).Returned by: POST /v1/recipe/execute
The body must name exactly one reference: send
audio_idorreference_url, not both and not neither, as a non-empty string.Returned by: POST /v1/audio/library/similar
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.
Returned by: 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, and 1 more
sha256is not 64 hexadecimal characters.Returned by: POST /v1/audio/uploads, POST /v1/audio/duplicates/check
invalid_sort
400sortis not a known short name or a list of{ key, dir }with known keys.Returned by: POST /v1/audio/views, PUT /v1/audio/views/{viewId}, POST /v1/audio/library/query
sort_dirmust beascordesc.Returned by: GET /v1/audio/library
sort_keyis not one of the supported sort keys.Returned by: GET /v1/audio/library
starredis missing or nottrueorfalse.Returned by: POST /v1/audio/star
Only
status=uploadingis supported when listing sessions.Returned by: GET /v1/audio/uploads
invalid_tag
400A tag name is empty, not a string, or contains a NUL character(or
fromof a merge is not a list of 1 to the allowed number of names).error.details.fieldnames the field.Returned by: POST /v1/audio/tags, POST /v1/audio/tags/rename, POST /v1/audio/tags/merge, PUT /v1/audio/tags/color, POST /v1/audio/tags/adopt
titlemust be a string.Returned by: POST /v1/conversations
invalid_to
400tois not a real ISO 8601 date or timestamp.Returned by: GET /v1/conversations
invalid_url
400A link in the request cannot be used: it is missing, empty, too long, not an absolute address, not
httporhttps, or points to a private or internal address.Returned by: POST /v1/audio/imports, POST /v1/media/refresh-url
versionIdis not valid percent-encoding. Encode it as a URL path segment.Returned by: GET /v1/audio/versions/{versionId}/audio-url
version_ofis not theaudio_idof one of your ready files.Returned by: POST /v1/audio/uploads
The view id in the path is not a UUID.
Returned by: PUT /v1/audio/views/{viewId}, DELETE /v1/audio/views/{viewId}
webhook_urlis not an https URL that resolves to a public address.Returned by: POST /v1/batch, POST /v1/recipe/execute, POST /v1/webhooks
messageis longer than 32000 characters.Returned by: POST /v1/batch
The
afterquery value is missing. Send a time in milliseconds since the Unix epoch.Returned by: DELETE /v1/documents/{id}
audio_idis missing or not a string.Returned by: POST /v1/audio/best, POST /v1/audio/rename
audio_idsis missing, empty, or not a list of strings.Returned by: 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
The body has no
audio_url. Name the audio file to analyze.Returned by: POST /v1/analyze, POST /v1/conversations
The body has no
audio_urls, or the array is empty. Send between 1 and 500 audio URLs.Returned by: POST /v1/batch/estimate, POST /v1/batch
missing_body
400The 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.
Returned by: PUT /v1/audio/upload/{fileId}, PUT /v1/audio/uploads/{sessionId}/parts/{n}, POST /v1/audio/{audioId}/notes
The upload request declares no size. Send
content_lengthas a positive integer. (A part sent to the API-side part route without aContent-Lengthheader is refused with HTTP 411 and this same code.)Returned by: POST /v1/audio/upload-url, PUT /v1/audio/uploads/{sessionId}/parts/{n}
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.Returned by: 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, and 3 more
missing_file
400The upload has no
filepart. Send the audio in a part namedfile.Returned by: POST /v1/upload
The session request has no
filename. Send the name of the file.Returned by: POST /v1/audio/uploads
The path has no
job_id.Returned by: GET /v1/analyze/{job_id}, POST /v1/analyze/{job_id}/cancel, GET /v1/analyze/{job_id}/logs, GET /v1/chat/{job_id}
missing_name
400nameis missing, blank, or not a string.Returned by: POST /v1/audio/rename, POST /v1/audio/views, POST /v1/audio/views/{viewId}/save
The body has no
prompt. Send the message to the assistant.Returned by: POST /v1/chat
The body has no
recipe_id. Name the recipe to run on every file.Returned by: POST /v1/batch/estimate, POST /v1/batch, POST /v1/audio/library/batch
missing_size
400The session request has no valid
size_bytes. Send the size of the whole file as a positive integer.Returned by: POST /v1/audio/uploads
The
titleis missing or blank. A body that is not valid JSON is reported the same way.Returned by: POST /v1/documents
The path has no view id.
Returned by: PUT /v1/audio/views/{viewId}, DELETE /v1/audio/views/{viewId}
A name or label is longer than the allowed number of characters. The error message states the limit for that field.
Returned by: 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
400The recipe was not made by forking another, so there is nothing to compare it with.
Returned by: GET /v1/recipe/{recipe_id}/compare
The update changes nothing: send a
name, adefinitionor aconfig.Returned by: PUT /v1/audio/views/{viewId}
tag_too_long
400A tag is longer than the allowed number of characters.
Returned by: 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
The
titleis longer than 200 characters.Returned by: POST /v1/conversations, POST /v1/documents
More than 5000 file ids in one request. Send them in several calls.
Returned by: POST /v1/audio/tags, POST /v1/audio/tags/selection-state, POST /v1/audio/star
More than 50 distinct files, or more than 500 entries, were sent in one import request (repeats are ignored below that bound).
Returned by: POST /v1/audio/imports
too_many_ids
400audio_idsnames more than 100 ids. Send them in several calls.Returned by: POST /v1/audio/archive, POST /v1/audio/bulk-delete, POST /v1/audio/trash/restore, POST /v1/audio/trash/delete-forever
More than 2 media items were attached to one message.
Returned by: POST /v1/chat
The file could not be read as audio.
error.details.supported_formatslists the accepted formats; if yours is one of them the file may be damaged, so export it again.Returned by: POST /v1/analyze, POST /v1/recipe/execute
The import source is not available.
providermust belink,google_driveordropbox.Returned by: POST /v1/audio/imports
The simple upload takes audio only. Upload video through the presigned upload route.
Returned by: POST /v1/upload
HTTP 401
The Authorization header is not in the form
Bearer <key>.Returned by: 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, and 120 more
invalid_key
401The key is unknown or has been revoked. Create a new key in your dashboard.
Returned by: 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, and 120 more
The key does not look like a Scarleta API key. Paid keys start with
scar_live_, free keys withsk_free_.Returned by: 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, and 120 more
The Authorization header has the Bearer scheme but no key after it.
Returned by: 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, and 120 more
missing_auth
401The request has no Authorization header. Send your API key as
Authorization: Bearer <key>.Returned by: 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, and 120 more
HTTP 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.
Returned by: POST /v1/batch, POST /v1/analyze, POST /v1/recipe/generate, POST /v1/recipe/execute, POST /v1/audio/library/batch
HTTP 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.
Returned by: POST /v1/batch/estimate, POST /v1/batch, POST /v1/audio/library/batch
Sound grouping is available on paid accounts only, and this key belongs to a free account.
Returned by: POST /v1/audio/library/cluster
forbidden
403The request asks for something your account may not do, for example setting
catalog_statuson a template recipe.Returned by: POST /v1/recipe/save
The upload URL has expired, was already used, or its token is wrong. Request a new upload URL.
Returned by: PUT /v1/audio/upload/{fileId}
The part URL has expired or its token is wrong. Ask for a new URL.
Returned by: PUT /v1/audio/uploads/{sessionId}/parts/{n}
A file named in the request belongs to a different account. Use files from your own library or a public URL.
Returned by: POST /v1/batch, POST /v1/analyze, POST /v1/chat, POST /v1/conversations, POST /v1/recipe/execute
HTTP 404
No archive with this id in your account.
Returned by: GET /v1/audio/archives/{jobId}, GET /v1/audio/archives/{jobId}/parts/{n}/url
The archive has no part with this number (a one-time download link has no parts).
Returned by: GET /v1/audio/archives/{jobId}/parts/{n}/url
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.
Returned by: POST /v1/analyze, POST /v1/recipe/execute, POST /v1/audio/library/query, GET /v1/audio/library/similar/{audio_id}, POST /v1/audio/library/similar
No batch with this id exists for your account.
Returned by: GET /v1/batch/{batch_id}, GET /v1/batch/{batch_id}/results, DELETE /v1/batch/{batch_id}, POST /v1/batch/{batch_id}/retry
The grouping job has no group with this id.
Returned by: PUT /v1/audio/library/cluster/{job_id}/groups/{group_id}
The sound grouping job does not exist or belongs to another account.
Returned by: 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}
The conversation does not exist or belongs to another account.
Returned by: POST /v1/chat
The file has no cover image. Set one first.
Returned by: GET /v1/audio/{audioId}/cover
No file or version with this id exists in your account (or it is already deleted). Check the id.
Returned by: 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
At least one of the requested files is not in your library.
error.details.missinglists the ids.Returned by: POST /v1/audio/archives
No import with this id in your account.
Returned by: GET /v1/audio/imports/{importId}
No job with this id exists for your account.
Returned by: GET /v1/analyze/{job_id}, POST /v1/analyze/{job_id}/cancel, GET /v1/analyze/{job_id}/logs, GET /v1/chat/{job_id}
The file has no melody analysis with a MIDI export, or it is not yours.
Returned by: GET /v1/audio/{audioId}/midi
The account has no signing secret yet, so there is nothing to revoke.
Returned by: POST /v1/webhooks/signing-secret/revoke
not_found
404The resource does not exist, is already gone, or is not visible to your account.
Returned by: 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, and 34 more
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.
Returned by: POST /v1/batch/estimate, POST /v1/recipe/cancel, POST /v1/audio/library/batch
The recipe this fork was made from is deleted or not visible to you.
Returned by: GET /v1/recipe/{recipe_id}/compare
No upload session with this id in your account.
Returned by: GET /v1/audio/uploads/{sessionId}, POST /v1/audio/uploads/{sessionId}/part-urls, POST /v1/audio/uploads/{sessionId}/complete, POST /v1/audio/uploads/{sessionId}/abort
The saved view does not exist or is not yours.
Returned by: 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
No active registered webhook address with this id exists for your account.
Returned by: DELETE /v1/webhooks/{id}
HTTP 409
The archive has not finished building. Read it until its status is
completed, then ask for the part.Returned by: GET /v1/audio/archives/{jobId}/parts/{n}/url
The batch already finished, so it cannot be cancelled.
Returned by: DELETE /v1/batch/{batch_id}
Only a batch that ended with failed or cancelled items can be retried. This one is still running or fully completed.
Returned by: POST /v1/batch/{batch_id}/retry
The document is a visual card (
kindcard); cards are read-only, so editing or deleting versions is refused.Returned by: POST /v1/documents, DELETE /v1/documents/{id}
A sound grouping of yours is already queued or running.
error.details.job_idnames it. Wait for it to finish.Returned by: POST /v1/audio/library/cluster
The grouping job has not completed, so its groups cannot be named yet.
Returned by: PUT /v1/audio/library/cluster/{job_id}/groups/{group_id}
The reference file has no sound fingerprint yet. Run the embedding analysis on it first.
Returned by: POST /v1/audio/library/query, GET /v1/audio/library/similar/{audio_id}, POST /v1/audio/library/similar
This
Idempotency-Keywas already used with a different request. Use a new key for a different batch.Returned by: POST /v1/batch
A part has the wrong size. Upload it again at the exact part size.
Returned by: POST /v1/audio/uploads/{sessionId}/complete
Some parts have not been uploaded. Upload the missing parts (the response lists them), then complete again.
Returned by: POST /v1/audio/uploads/{sessionId}/complete
No message of the conversation matches the position and guards you sent. Nothing was deleted. Read the conversation again and retry with current values.
Returned by: POST /v1/conversations/{conversation_id}/rewind
The session already completed or was cancelled, so it cannot take parts or be completed again.
Returned by: 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}
The signing secret was revoked, so none is returned and no webhook is delivered. Rotate to create a new one.
Returned by: GET /v1/webhooks/signing-secret
The uploaded parts add up to more than the size declared when the session started.
Returned by: POST /v1/audio/uploads/{sessionId}/complete
A turn is already running in this conversation. Wait until
GET /v1/conversations/{id}/statusreports no active turn, or cancel it, then send again.Returned by: POST /v1/chat, POST /v1/conversations/{conversation_id}/rewind
The upload was cancelled before it could complete. Start a new session.
Returned by: POST /v1/audio/uploads/{sessionId}/complete
The account already has 5 registered webhook addresses. Delete one, then register again.
Returned by: POST /v1/webhooks
HTTP 410
The archive is past its retention time and can no longer be downloaded. Start a new one.
Returned by: GET /v1/audio/archives/{jobId}/parts/{n}/url
HTTP 413
The document
contentis longer than 1048576 characters.Returned by: POST /v1/documents
The file is over the size limit of this route. Use a presigned upload or an upload session for larger files.
Returned by: 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
The cover image is larger than 4 MiB. Send a smaller image.
Returned by: PUT /v1/audio/{audioId}/cover
metadatais larger than 16384 bytes once serialized.Returned by: POST /v1/batch
The part is larger than the session part size.
Returned by: PUT /v1/audio/uploads/{sessionId}/parts/{n}
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).
Returned by: POST /v1/chat, PATCH /v1/audio/{audioId}/details
promptis longer than 32768 characters. Shorten it.Returned by: POST /v1/chat
The recipe is larger than 102400 bytes once serialized. Shorten it.
Returned by: POST /v1/recipe/validate, POST /v1/recipe/save, POST /v1/recipe/{recipe_id}/fork, POST /v1/recipe/approve, POST /v1/recipe/execute
The file does not fit in your storage. Delete files or add tokens, then retry.
Returned by: POST /v1/audio/upload-url, POST /v1/audio/uploads
webhook_urlis longer than 4096 bytes.Returned by: POST /v1/batch, POST /v1/recipe/execute, POST /v1/webhooks
HTTP 415
The stored file is not a supported audio or media file.
Returned by: POST /v1/audio/{fileId}/download-url
not_audio
415The assembled file is not a supported audio or video file. It was removed.
Returned by: POST /v1/audio/uploads/{sessionId}/complete
HTTP 422
The batch has more than 500 files. Split it into several batches.
Returned by: POST /v1/batch/estimate, POST /v1/batch
More than 5000 files would be grouped. Add filters to narrow the selection.
Returned by: POST /v1/audio/library/cluster
Fewer files with a sound fingerprint match than the number of groups asked for.
error.details.file_countsays how many were found.Returned by: POST /v1/audio/library/cluster
The view or filters match no file, so there is nothing to run.
error.details.matched_countis 0.Returned by: POST /v1/audio/library/batch
More files match than
max_itemsallows. Add filters or raisemax_itemsup to the limit.error.details.matched_countsays how many matched.Returned by: POST /v1/audio/library/batch
HTTP 429
Too many requests for this key or route. Wait for the number of seconds in the
Retry-Afterheader, 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, untilRetry-Afterelapses. Clients behind a shared address (office or NAT egress) can be affected by another client on it.Returned by: 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, and 124 more
Too many unfinished upload sessions. Finish or cancel some, then start again.
Returned by: POST /v1/audio/uploads
HTTP 500
The analysis request failed unexpectedly. Retry; contact support with the
request_idif it persists.Returned by: POST /v1/analyze
The analysis could not be started. Nothing was charged; retry.
Returned by: POST /v1/analyze
The batch record has no recipe on our side, so it cannot be retried. Contact support with the
request_idif you need it recovered. (A batch whose recipe was deleted answers 404not_foundinstead.)Returned by: POST /v1/batch/{batch_id}/retry
The batch record is incomplete on our side. Contact support with the
request_id.Returned by: POST /v1/batch/{batch_id}/retry
chat_failed
500The message could not be processed. Retry; contact support with the
request_idif it persists.Returned by: POST /v1/chat
The analysis service is not available. Retry shortly; contact support with the
request_idif it persists.Returned by: POST /v1/analyze
The item could not be created. Retry; contact support with the
request_idif it persists.Returned by: POST /v1/conversations, POST /v1/documents
The item could not be deleted. Retry.
Returned by: DELETE /v1/conversations/{conversation_id}, DELETE /v1/documents/{id}
get_failed
500The item could not be read. Retry.
Returned by: GET /v1/conversations/{conversation_id}, GET /v1/documents/{id}
list_failed
500The list could not be read. Retry.
Returned by: GET /v1/conversations, GET /v1/conversations/{conversationId}/shares, GET /v1/documents
The conversation progress could not be read. Retry.
Returned by: GET /v1/conversations/{conversation_id}/live-status
The conversation could not be marked read. Retry.
Returned by: PUT /v1/conversations/{conversation_id}/mark-read
mint_failed
500The share link could not be created. Retry; contact support with the
request_idif it persists.Returned by: POST /v1/conversations/{conversationId}/shares
The job could not be read. Retry.
Returned by: GET /v1/analyze/{job_id}, GET /v1/chat/{job_id}
The share link could not be revoked. Retry.
Returned by: DELETE /v1/conversations/{conversationId}/shares/{shareId}
The conversation could not be rewound. Nothing is guaranteed to have been deleted: read the conversation, then retry.
Returned by: POST /v1/conversations/{conversation_id}/rewind
save_failed
500The recipe could not be saved. Retry; contact support with the
request_idif it persists.Returned by: POST /v1/recipe/save
The recipe runner is not configured in this environment. It is a deployment fault; contact support with the
request_id.Returned by: POST /v1/recipe/execute
The batch could not be started. Nothing was charged; retry, with the same
Idempotency-Keyif you sent one.Returned by: POST /v1/batch, POST /v1/batch/{batch_id}/retry
HTTP 502
The conversation could not accept a new turn right now. Retry shortly.
Returned by: POST /v1/chat, GET /v1/conversations/{conversation_id}/status, POST /v1/conversations/{conversation_id}/cancel, POST /v1/conversations/{conversation_id}/rewind
The decline could not be saved. Nothing was cancelled; retry.
Returned by: POST /v1/recipe/cancel
stop_failed
502The in-flight run could not be stopped. Nothing was recorded for a post-confirm Stop; a pre-confirm Cancel is never refused for this reason. Retry.
Returned by: POST /v1/recipe/cancel
The turn could not be started. Nothing was charged; retry.
Returned by: POST /v1/chat
Chat is temporarily unavailable. Retry shortly; contact support with the
request_idif it persists.Returned by: POST /v1/chat
The recipe run could not be started. Nothing was charged; retry.
Returned by: POST /v1/recipe/execute
HTTP 503
Conversation tracking is temporarily unavailable. Retry shortly.
Returned by: GET /v1/conversations/{conversation_id}/status, POST /v1/conversations/{conversation_id}/cancel, POST /v1/conversations/{conversation_id}/rewind
The job could not be recorded. Nothing was charged; retry.
Returned by: POST /v1/analyze
Chat is temporarily unavailable. Retry shortly; contact support with the
request_idif it persists.Returned by: POST /v1/chat