Errors

This page lists every error the /v1 endpoints return: the HTTP status, the exact errorMessage, the condition that raises it and the fix. It is for the engineer writing the error branch of a client. Failures of asynchronous jobs, which are not HTTP errors, are at the end.

Error response shape

Every error is one JSON object with the same four fields as a successful response. success is false, data is null, statusCode repeats the HTTP status and errorMessage is the string quoted in the tables below. Every error on a /v1 path also carries docs, a link to this page. A 401 links the Authentication page instead.

{
  "data": null,
  "statusCode": 400,
  "success": false,
  "errorMessage": "text must be shorter than or equal to 500 characters",
  "docs": "https://echonova.ai/docs/developers/errors"
}

When several validation rules fail on one request, their messages are joined into one errorMessage, separated by a comma and a space. Match on the status first and on the message second. The message is plain text, not a code, and a change to one is listed on the Changelog.

Authentication

Raised before the endpoint runs. Every 401 carries the same message, so the body does not say which of its five causes applied. The full check order is on Authentication.

Rate limit, credit limit and balance

Two different errors use status 429. Read errorMessage before you retry: one clears with time, the other does not.

Request validation

Raised by the body or query validation before any work runs. Nothing is charged. Leading and trailing whitespace is trimmed from every string before these rules are checked, and unknown fields are rejected.

Uploads

Raised on POST /v1/speech-to-text, POST /v1/speech-to-text/sync and POST /v1/sound-cleaning while the file is received or checked. Nothing is charged. The language, numbers_as_digits and identify_speakers rows apply to the two Speech to Text endpoints only.

Sound Cleaning

Raised on POST /v1/sound-cleaning, in addition to the upload errors above.

Not found

The same three 404 messages come from GET and DELETE on a job, and STT Job not found also from downloading one. A key deletes the API jobs of its workspace, whichever key created them, so a job of another workspace answers 404.

Deleting jobs

Raised by DELETE /v1/text-to-speech/jobs/{jobId}, DELETE /v1/speech-to-text/jobs/{jobId} and DELETE /v1/sound-cleaning/jobs/{jobId}.

Downloading transcripts

Raised by GET /v1/speech-to-text/jobs/{jobId}/export, in addition to the authentication, rate-limit and service errors, Invalid identifier, property <name> should not exist and STT Job not found above. Downloading is not charged. A success is the file itself; an error is the usual error object.

Widget tickets

Raised by POST /v1/widgets/{publicId}/tickets. Minting a ticket is free. Nothing is charged.

Service errors

Speech generation and transcription run during both synchronous calls and start during both asynchronous calls. When the work is not accepted, the charge is refunded and the request fails with one of these.

Failures on asynchronous jobs

An asynchronous job that fails after it was accepted does not return an HTTP error. The job's status becomes failed, its error field holds the reason, the credits are refunded, and in most cases a job.failed webhook is sent. creditsConsumed keeps the number that was charged.

The timeout sends no webhook, so a client that waits only for job.completed or job.failed never hears about it. Poll GET /v1/text-to-speech/jobs/{jobId} or GET /v1/speech-to-text/jobs/{jobId} when no event has arrived 15 minutes after the POST. Event bodies are on Webhook events.

Code samples

Read the status, then errorMessage. Retry only the rate-limit 429, after Retry-After seconds, and the 503 and 504 errors. Which retries are free and which create a second job is on Retry requests safely.

curl -s -o response.json -w "%{http_code}" \
  -X POST "https://api.echonova.ai/v1/text-to-speech/sync" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "", "voiceId": "VOICE_ID"}'
# prints 400; response.json holds "text must be longer than or equal to 1 characters, text should not be empty"

import time
import requests

response = requests.post(
    "https://api.echonova.ai/v1/text-to-speech/sync",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"text": "", "voiceId": "VOICE_ID"},
)
body = response.json()
if not body["success"]:
    message = body["errorMessage"]
    if response.status_code == 429 and "Retry-After" in response.headers:
        time.sleep(int(response.headers["Retry-After"]))
        # retry the request
    elif response.status_code in (503, 504):
        time.sleep(5)
        # retry the request
    else:
        raise RuntimeError(f"{response.status_code}: {message}")

const response = await fetch('https://api.echonova.ai/v1/text-to-speech/sync', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ text: '', voiceId: 'VOICE_ID' }),
});
const body = await response.json();
if (!body.success) {
  const retryAfter = response.headers.get('Retry-After');
  if (response.status === 429 && retryAfter) {
    await new Promise((r) => setTimeout(r, Number(retryAfter) * 1000));
    // retry the request
  } else if (response.status === 503 || response.status === 504) {
    await new Promise((r) => setTimeout(r, 5000));
    // retry the request
  } else {
    throw new Error(`${response.status}: ${body.errorMessage}`);
  }
}

FAQ

Which errors are safe to retry?

The rate-limit 429, after Retry-After seconds, and every 503 and 504. A 400, 401, 403, 404 or 402 returns the same answer until you change the request, the key or the balance. Which retries create a second job is on Retry requests safely.

Is anything charged when I get an error?

No. Every error listed above is raised before the charge, or the charge is refunded before the error is returned.

Why are there two 429 responses?

One is the request rate limit and clears with time; it carries Retry-After. The other is the key's Credit Limit and clears only when you raise the limit or the billing cycle turns; it carries no header. Tell them apart by errorMessage.

Why does every 401 say the same thing?

Unauthorized covers a missing or malformed header, an unknown key, a deleted key, a disabled key and a closed account. Check the header first, then the key's Status under Developers, API Keys.

Can I match on errorMessage in code?

Yes, after matching on the status. The messages are plain text and any change to one is listed on the Changelog.

Related

• Authentication
• Rate limits
• Credits
• Text to Speech voices and options
• Speech to Text formats and output
• Webhook events
• Retry requests safely
• Read the request log