Basics
Errors
One error shape for every refusal, its codes by status, and the few answers that come from in front of the api.
Every refusal the api makes is JSON of one shape, with an HTTP status that says what kind of refusal it is:
{ "error": { "code": "not_found", "message": "no such character" } }codeis stable and meant for your code: branch on it.messageis a sentence for people. It may change, so don't match on it.
A message never carries the words of the systems behind a call. When a call fails on our side, you see a plain sentence such as "The call couldn't start. Nothing was charged.", never a vendor's error.
Codes by status
| Status | Codes on /v1 |
|---|---|
| 400 | invalid_json, invalid_field, invalid_idempotency_key, invalid_url, unsafe_url, unsupported_file, invalid_meeting_url, consent_required |
| 401 | invalid_api_key |
| 402 | insufficient_balance |
| 403 | org_disabled |
| 404 | not_found (also an unknown /v1 path), no_recording |
| 405 | method_not_allowed |
| 409 | price_not_set, tier_unavailable, meeting_exists, meeting_dispatched, meeting_over, idempotency_in_progress, idempotency_failed, webhook_limit, webhook_disabled, knowledge_too_large, document_not_ready, not_a_link, asset_limit, name_taken, voice_limit, recording_not_ready, call_running, icon_in_use |
| 413 | file_too_large |
| 422 | idempotency_mismatch, fetch_failed, meeting_not_found, clone_failed, mcp_refresh_failed |
| 429 | rate_limited, too_many_calls, test_limit |
| 500 | internal (the detail is only in our log) |
| 503 | engine_unavailable, call_not_started, unavailable, recording_unavailable, voice_clone_unavailable |
Each endpoint in the reference lists the codes it can answer and why.
The ones you'll meet most
- 400
invalid_json: the body isn't JSON,Content-Type: application/jsonis missing, or the body has a field the endpoint doesn't know. - 400
invalid_field: a field is the wrong type, too long, or out of range. The message names the field. - 402
insufficient_balance: the balance can't cover the shortest call (30 seconds). - 409
price_not_set: the character's tier has no price yet, so paid calls can't start. - 409
meeting_exists: the character is already going to that meeting at that time. This one error carries one more field,error.meeting_id: the meeting already going. See Meetings. - 429: slow down.
rate_limitedandtoo_many_callscome with aRetry-Afterheader;test_limitdoesn't. See Limits. - 503
engine_unavailable,call_not_started: the call couldn't start. Nothing was charged; try again in a minute.
Answers in another shape
A few answers come from the proxy in front of the api, not from the api itself:
| Status | Body | Why |
|---|---|---|
| 429 | plain text | Too many requests from one address. See Limits |
| 413 | plain text | A body over 11 MB, refused before it reaches the api. See Limits |
| 503 | {"error":{"code":"unavailable",…}} | The api is restarting. Try again in a moment |
Handling codes you don't know
New codes may be added. Handle a code you don't recognise by its status: a 4xx means change the request, a 429 means wait, a 5xx means try again later.
const res = await fetch("https://api.daxov.com/v1/calls", init);
if (!res.ok) {
const { error } = await res.json().catch(() => ({ error: { code: "unknown" } }));
if (res.status === 429) {
const wait = Number(res.headers.get("retry-after") ?? 30);
// try again in `wait` seconds (test_limit sends none: try tomorrow)
} else if (error.code === "insufficient_balance") {
// the balance needs credit before more paid calls can start
}
}