Errors

Error response format

Every error follows the same structured envelope:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of what went wrong.",
    "httpStatus": 401
  },
  "status": "error",
  "status_code": 401
}

The HTTP status always matches status_code and error.httpStatus; there is no “200 on error”. Branch on either the status or error.code.

Successful responses do not share one envelope: some wrap the result as {"success": true, "data": …} (agents, credits, video), some as {"status": "success", "status_code": 200, "data": …} (/v1/me, embed tokens), and some return a bare object (/v1/validate, /speak). Each endpoint’s page shows its response.

502 and 504 may not be JSON

A 502 or 504 comes either from the API (the envelope above, code UPSTREAM_UNAVAILABLE or UPSTREAM_TIMEOUT) or from the delivery network in front of it (an HTML page). Check Content-Type before parsing any error, and fall back to the HTTP status line when it is not application/json. Both are transient: retry after Retry-After seconds when present, otherwise back off.

HTTP status codes

Error codes

Authentication

Plan and credit refusals

A plan or credit refusal names its fix in a link field of error: send the user there rather than retrying.

Until 2026-10-19, a Free account’s runtime-token and meter responses carry a plan_notice field and an X-Bithuman-Plan-Notice header: “Free-plan API and SDK access ends on 2026-10-19. Upgrade at https://www.bithuman.ai/pricing to keep it.” A Free account with top-up credits bought before 2026-09-27 keeps access until those credits are spent, and its notice says so. Show plan_notice as sent. Choose a plan · top up.

Agent operations

Model errors

Agent creation, adding a model, model download, embed tokens and talking video share these codes:

File operations

Session & infrastructure

Knowledge bases

The CLI’s exit codes, such as PUBLIC_BIND_REFUSED, are on CLI troubleshooting. The Flutter plugin’s codes, such as MODEL_REJECTED, are on Flutter errors, and the Android SDK’s refusals on Android troubleshooting.

Handling errors in Python

The Python examples use requests (pip install requests). This call is free: it asks for the status of an agent that does not exist.

import os, requests

resp = requests.get(
    "https://api.bithuman.ai/v1/agent/status/A00XXX0000",
    headers={"api-secret": os.environ["BITHUMAN_API_SECRET"]},
    timeout=30,
)
if resp.ok:
    print(resp.json()["data"]["status"])
elif resp.headers.get("content-type", "").startswith("application/json") and "error" in resp.json():
    err = resp.json()["error"]
    print(resp.status_code, err["code"], err["message"])  # 404 NOT_FOUND here
else:
    print(resp.status_code, "retry after", resp.headers.get("Retry-After"))

Retry 429 and 5xx with exponential backoff and jitter (rate limits). For a plan or credit refusal, follow its link field; fix the request for any other 4xx. Is the API down? Check status.bithuman.ai.

curl https://api.bithuman.ai/readyz
# → {"status":"ok","families":{"sessions":{"status":"ok"}, ...}}

import requests

resp = requests.get("https://api.bithuman.ai/readyz")
print(resp.json())

const resp = await fetch("https://api.bithuman.ai/readyz");
console.log(await resp.json());

{
  "status": "ok",
  "window_seconds": 900,
  "replica_scope": "this process only — not a fleet view"
}