Docs / Platform

Errors

Waridi uses standard HTTP status codes and returns a JSON body that tells you what went wrong and what to do about it.

Error format

{
  "error": {
    "type": "invalid_request",
    "code": "unsupported_language",
    "message": "language 'sw-UG' is not available yet. Use 'sw-TZ' or 'sw-KE'.",
    "param": "language",
    "request_id": "req_01J9ZH6C2V"
  }
}
Field Description
type Broad category. Safe to branch on
code Specific reason. Safe to branch on
message Human-readable explanation. Wording may change, so do not parse it
param The request field at fault, when there is one
request_id Same as the X-Request-Id header. Include it when you contact us

Error codes

Status Type Code What to do
400 invalid_request missing_parameter Add the field named in param
400 invalid_request invalid_parameter Fix the value of param
400 invalid_request text_too_long Split text into chunks within your plan limit
401 authentication_error missing_api_key Send Authorization: Bearer <key>
401 authentication_error invalid_api_key Check the key, or create a new one in Studio
403 permission_error permission_denied Your plan does not include this feature
403 permission_error consent_required A clone request is missing a valid consent recording
403 permission_error voice_revoked The voice owner withdrew consent. Pick another voice
404 not_found voice_not_found Check the voice ID, and that it belongs to this environment
404 not_found resource_not_found The agent, job or session ID does not exist
409 conflict voice_not_ready The cloned voice is still being verified or trained
413 invalid_request file_too_large Upload a shorter file or use audio_url
415 invalid_request unsupported_audio_format Convert to WAV, MP3, Ogg/Opus, FLAC, M4A or WebM
422 invalid_request unsupported_language Use sw-TZ, sw-KE or auto
422 invalid_request audio_unreadable The file is empty, silent or corrupted
429 rate_limit_error rate_limited Wait for Retry-After, then retry
429 rate_limit_error quota_exceeded Monthly audio allowance used up. Upgrade or wait for reset
500 api_error internal_error Our fault. Retry with backoff
503 api_error overloaded Temporary capacity issue. Retry with backoff

Errors on the stream

On wss://api.waridi.io/v1/stream, recoverable problems arrive as an error event and the session stays open. Fatal problems arrive as an error event followed by a close code. See Streaming → Limits and close codes.

{"type": "error", "code": "invalid_audio_frame", "message": "Expected mulaw at 8000 Hz.", "fatal": false}

Handling errors in the SDKs

from waridi import Waridi, WaridiError, RateLimitError

client = Waridi()

try:
    audio = client.tts.create(model="sauti-standard", voice="zawadi", text="Asante sana!")
except RateLimitError as e:
    print("Slow down, retry after", e.retry_after, "seconds")
except WaridiError as e:
    print(e.status, e.code, e.request_id)

import { Waridi, WaridiError, RateLimitError } from "@waridi/sdk";

const client = new Waridi();

try {
  await client.tts.create({ model: "sauti-standard", voice: "zawadi", text: "Asante sana!" });
} catch (e) {
  if (e instanceof RateLimitError) console.log("Retry after", e.retryAfter);
  else if (e instanceof WaridiError) console.log(e.status, e.code, e.requestId);
  else throw e;
}

curl -i https://api.waridi.io/v1/tts \
  -H "Authorization: Bearer $WARIDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "sauti-standard", "voice": "nobody", "text": "Habari"}'
# HTTP/2 404 ... "code": "voice_not_found"

Still stuck?

Write to hello@waridi.io with the request_id, what you sent (without your API key) and what you expected.

PreviousRate limits