Errors
View as Markdown · Open in Claude Desktop
An error answers with the HTTP status below and a JSON body.
{
"error": {
"code": "LIMIT",
"message": "This call needs more allowance than you have left.",
"fix": "Wait for the reset or add time.",
"reason": "allowance",
"meter": "voice_ai",
"resetsAt": "2026-12-01T00:00:00Z",
"requestId": "req_123"
}
}
code is stable and safe to branch on. message and fix are for people and may change. Quote requestId when you contact support. The SDKs raise a typed error with these fields.
| Code | HTTP status | Retry | Reasons | How to fix it |
|---|---|---|---|---|
BAD_REQUEST |
400 | no | test_mode_sample_only, device_only, no_face, client_outdated |
Read param in the error to find the field, correct it and send the request again. With a test key, use only the sample files named in the error. |
UNAUTHENTICATED |
401 | after re-auth | missing, invalid, key_revoked, token_expired, reauth_required |
Send Authorization: Bearer <key> with a key that is valid and not revoked. Sign in again if you use OAuth and the token expired. |
INACTIVE |
401 | no | expired, refunded, revoked, payment_failed, suspended |
The account or plan is no longer active. Open your account to see why, then renew or fix the plan. |
NEEDS_PLAN |
402 | after purchase | paid_feature, subscribers_only |
The feature is part of a paid plan. Choose a plan on the pricing page, then send the request again. |
LIMIT |
402 | after resetsAt or a purchase | allowance, key_cap, storage_cap, no_free_allowance, network, spend_ceiling |
Read reason, meter and resetsAt. Wait for the reset, buy a top-up or a plan, or lower the size of the job. |
DECLINED |
402 | user action | provider_decline |
The payment provider declined the payment. Use another payment method. |
FORBIDDEN_SCOPE |
403 | no | missing_scope, web_only |
The key or token lacks a scope. Create a key with the scope named in param. Voice cloning is available only in the web app. |
VOICE_PROTECTED |
403 | no | none | The voice is protected and cannot be used. Choose a different voice. |
NOT_FOUND |
404 | no | result_lost |
The id does not exist for this account, or the result was removed. Check the id and run the job again if the result is lost. |
CONFLICT |
409 | no | none | The request conflicts with the current state. Fetch the current state and try again. |
IDEMPOTENCY_MISMATCH |
409 | no | none | You reused an Idempotency-Key with a different body. Use a new key for a new request. |
DEVICE_LIMIT |
409 | no | none | The account has reached its device limit. Remove a device you no longer use. |
ALREADY_SUBSCRIBED |
409 | no | none | The account already has this plan. Change or manage the plan from the billing page. |
QUOTE_CHANGED |
409 | after a new quote | none | The price changed since the quote. Ask for a new quote and confirm it. |
BILLING_OP_IN_PROGRESS |
409 | later | none | A billing change is still running. Wait a moment and try again. |
RESUME_FIRST |
409 | after resume | none | The subscription is paused. Resume it, then send the request again. |
PAYMENT_ISSUE |
409 | after fixing payment | none | The last payment failed. Fix the payment method on the billing page, then try again. |
GONE |
410 | no | none | The resource was deleted or has expired and cannot come back. Create it again. |
EXPIRED |
410 | no | input_expiring |
The input or link expired. Upload the file again or ask for a new link. |
TOO_BIG |
413 | no | resolution |
The file is larger than your plan allows. The error states the limit. Send a smaller file, or move to a plan with a higher limit. |
TOO_LONG |
413 | no | none | The media is longer than your plan allows. The error states the limit. Trim it first or use a plan with a higher limit. |
UNSUPPORTED_MEDIA |
415 | no | streams |
The file type or streams are not supported by this tool. Convert the file first. Call GET /v1/capabilities for the accepted formats. |
NOT_HEARD |
422 | no | none | No speech was found in the audio. Check that the file has speech and a sound track. |
TOO_SHORT |
422 | no | none | The input is shorter than this tool needs. Send a longer input. |
SOURCE_REFUSED |
422 | no | unreachable, not_a_file, video_platform, private_address, too_many_redirects |
We could not take the input from that URL. Read reason. Use a direct link to a public media file, or upload the file. |
PART_CORRUPT |
422 | no | none | An uploaded part failed its check. Send that part again. |
CONTENT_REFUSED |
422 | no | S1, S2, S3, S4, S5, S6, S7, S8, S9, S10, S11, S12, S13, S14, impersonation, blocked_hash, vendor_policy |
The content is not allowed by our content policy. Read reason. If an appeal_url is present, use it to appeal. |
CHECKOUT_UNAVAILABLE |
422 | later | none | Checkout cannot start now. Try again later. |
RATE_LIMITED |
429 | Retry-After | requests, concurrent_jobs |
You sent too many requests or have too many jobs running. Wait the number of seconds in Retry-After, then retry. |
BUSY |
503 | Retry-After | queue_full, vendor_throttled, subject_moving, moderation_unavailable |
The service is busy. Wait the number of seconds in Retry-After, then retry. You are not charged. |
UNAVAILABLE |
503 | later | feature_off, vendor_down, vendor_quota, maintenance |
A feature or vendor is down. Try again later. You are not charged. |
FAILED |
500 | one retry | timeout, admission_aborted |
The job failed on our side. Retry once. If it fails again, contact support with the requestId. You are not charged. |