Retry Voice Clone
A new attempt for a clone in failed, with the same sample. The clone goes back to
pending and takes a slot under the plan's cap again, so the checks are the same as
on creation (404 service_not_found, 402 no_subscription,
422 voice_clone_quota_exceeded).
Only failed can be retried: a ready clone already has its voice and
pending/cloning are still running — those get 409 voice_clone_not_retryable.
Required key permission: voices.write.
Parameters
Values go straight into the request line, and the URL is built for you. Below are each parameter’s type, whether it is required, and its allowed values.
- stringin pathrequired
Voice provider whose clones you work with:
cartesiaorfishaudio. Any other value does not match the route (404). The clone cap, the subscription rule and the clone ids are separate for each provider.The value goes straight into the request line above.
Allowed values - stringin pathrequired
Cartesia or Fish Audio voice clone UUID — 36 characters, not a number.
Take it from the clone's
idfield:POST /voices/cartesia/clones(or/voices/fishaudio/clones) returns it on creation and the matchingGET …/cloneslists it. This is not the clone'svoice_id(that one goes into a template). Someone else's clone returns404withreason: voice_clone_not_found.The value goes straight into the request line above.
Possible responses
200Success. The payload is in data.
Success. The payload is in data.
{
"success": true,
"message": "Success",
"data": {
"id": "01a10e08-2ee5-702c-b492-243c88fd966f",
"provider": "cartesia",
"display_name": "Noisy sample",
"language": "ru",
"description": null,
"status": "pending",
"voice_id": null,
"attempts": 2,
"error": null,
"created_at": "2026-10-05T17:40:02+00:00",
"completed_at": null,
"failed_at": null,
"banned_at": null,
"ban_reason": null
}
}Success flag. Branch on the HTTP status code instead: any 2xx response carries true here, while an error comes back in a different shape that need not contain this field at all.
A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code.
datarequiredThe clone with a new attempt queued — back in pending.
CartesiaVoiceCloneCartesiaVoiceClone
The clone with a new attempt queued — back in pending.
Clone UUID. Use it in /voices/cartesia/clones/{voiceClone}/… paths; it does NOT go into a template — voice_id does.
Clone provider — always cartesia.
Clone name given at creation.
Language of the sample (ISO 639-1), or null if none was sent.
Your description of the clone, or null.
Status: pending → cloning → ready or failed; archived — retired by the owner; banned — blocked by a moderator. Only ready can be used for narration.
The Cartesia voice id — the value for tts_settings.voice_id of a template with service_key: cartesia. Present only for ready, otherwise null.
Cloning attempt number: 1 on creation, +1 for every retry.
errorrequiredWhy the last attempt failed; null while there has been no failure.
nullableobject
Why the last attempt failed; null while there has been no failure.
Machine-readable failure code: processing_error, max_retries, network, timeout, dispatch_failed. Retry with POST /voices/cartesia/clones/{voiceClone}/retry; if processing_error keeps coming back, use a different sample.
Human-readable explanation of the failure, or null. Branch on reason, not on this text.
When the clone was created.
When the clone became ready; null until then.
When the last attempt failed; null if it has not.
When a moderator banned the clone (status = banned); null if it is not banned.
Reason for the ban given by the moderator, or null. A banned clone can be neither used nor archived.
401The key is missing, unknown, disabled or expired.
The key is missing, unknown, disabled or expired.
{
"success": false,
"message": "API key is missing. Provide it in the X-API-KEY header.",
"data": null
}Always false in error responses.
Error text in the key's language (set through the X-Locale header).
Always null when the request is rejected before processing.
402No live subscription that includes the provider's service (Cartesia or Fish Audio; reason: no_subscription). Returned only if that service is closed to paying from the balance.
No live subscription that includes the provider's service (Cartesia or Fish Audio; reason: no_subscription). Returned only if that service is closed to paying from the balance.
{
"success": false,
"message": "An active subscription is required.",
"reason": "no_subscription",
"error_code": "no_subscription"
}Always false in error responses.
The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes.
Machine-readable reason of a business refusal (for example, input_expired, insufficient_balance). Branch on it, not on the message text.
The same machine-readable code as in reason — a second name for the field. The values always match.
403The key lacks the voices.write permission.
The key lacks the voices.write permission.
{
"success": false,
"message": "This API key does not have permission to perform this action."
}Always false in error responses.
Error text in the key's language (set through the X-Locale header).
404The clone does not exist or belongs to someone else (reason: voice_clone_not_found). A voiceClone that is not a UUID does not match the route: reason: endpoint_not_found (a hint with the docs address, llm.md §6.1). Also reason: service_not_found — the service is closed to the key owner.
The clone does not exist or belongs to someone else (reason: voice_clone_not_found). A voiceClone that is not a UUID does not match the route: reason: endpoint_not_found (a hint with the docs address, llm.md §6.1). Also reason: service_not_found — the service is closed to the key owner.
{
"success": false,
"message": "Voice clone not found.",
"reason": "voice_clone_not_found",
"error_code": "voice_clone_not_found"
}Always false in error responses.
The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes.
Machine-readable reason of a business refusal (for example, input_expired, insufficient_balance). Branch on it, not on the message text.
The same machine-readable code as in reason — a second name for the field. The values always match.
409The clone is not in failed (it is already ready, still pending/cloning, or archived), or its sample has already been deleted (reason: voice_clone_not_retryable). Create a new clone instead.
The clone is not in failed (it is already ready, still pending/cloning, or archived), or its sample has already been deleted (reason: voice_clone_not_retryable). Create a new clone instead.
{
"success": false,
"message": "Only a clone that ended with an error can be retried.",
"reason": "voice_clone_not_retryable",
"error_code": "voice_clone_not_retryable"
}Always false in error responses.
The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes.
Machine-readable reason of a business refusal (for example, input_expired, insufficient_balance). Branch on it, not on the message text.
The same machine-readable code as in reason — a second name for the field. The values always match.
422The clone cap of the plan is reached (reason: voice_clone_quota_exceeded, the cap is in max).
The clone cap of the plan is reached (reason: voice_clone_quota_exceeded, the cap is in max).
{
"success": false,
"message": "Voice clone limit reached: no more than 3. Delete a clone you no longer need or wait for the current one to fail.",
"reason": "voice_clone_quota_exceeded",
"error_code": "voice_clone_quota_exceeded",
"max": 3
}Always false in error responses.
The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes.
Machine-readable reason of a business refusal (for example, input_expired, insufficient_balance). Branch on it, not on the message text.
The same machine-readable code as in reason — a second name for the field. The values always match.
The clone cap of your plan for the chosen provider: how many clones in pending, cloning and ready you may hold at once (clones of the other provider do not count). Archive a clone you no longer need to free a slot.
429The clone rate limit is exceeded (reason: rate_limit_exceeded): by default 6 attempts per minute and 60 per day per user, shared with the web cabinet and LumVoice cloning. Every attempt counts, including one rejected by validation. Wait retry_after seconds (the Retry-After header).
The clone rate limit is exceeded (reason: rate_limit_exceeded): by default 6 attempts per minute and 60 per day per user, shared with the web cabinet and LumVoice cloning. Every attempt counts, including one rejected by validation. Wait retry_after seconds (the Retry-After header).
{
"success": false,
"message": "Too many attempts. Please wait a moment and try again.",
"reason": "rate_limit_exceeded",
"error_code": "rate_limit_exceeded",
"retry_after": 30
}Always false in error responses.
Error text in the key's language (set through the X-Locale header).
Machine-readable failure reason — branch on this, not on the message text.
The same machine-readable code as in reason — a second name for the field. The values always match; branch on either.
How many seconds to wait before retrying (the same value is in the Retry-After header).
Nearby
This page for AI
API version 1.0.0