Made in 10Docs
GuidesAPI
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:

An error
{ "error": { "code": "not_found", "message": "no such character" } }
  • code is stable and meant for your code: branch on it.
  • message is 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

StatusCodes on /v1
400invalid_json, invalid_field, invalid_idempotency_key, invalid_url, unsafe_url, unsupported_file, invalid_meeting_url, consent_required
401invalid_api_key
402insufficient_balance
403org_disabled
404not_found (also an unknown /v1 path), no_recording
405method_not_allowed
409price_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
413file_too_large
422idempotency_mismatch, fetch_failed, meeting_not_found, clone_failed, mcp_refresh_failed
429rate_limited, too_many_calls, test_limit
500internal (the detail is only in our log)
503engine_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/json is 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_limited and too_many_calls come with a Retry-After header; test_limit doesn'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:

StatusBodyWhy
429plain textToo many requests from one address. See Limits
413plain textA 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.

Branching on an error
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
  }
}

On this page