Skip to main content

​
Error Response Format

All error responses follow a consistent format: 
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of what went wrong.",
    "httpStatus": 401
  },
  "status": "error",
  "status_code": 401
}

​
HTTP Status Codes

StatusMeaningCommon Cause
200SuccessRequest completed
400Bad RequestInvalid parameters or missing required fields
401UnauthorizedInvalid or missing api-secret header
404Not FoundAgent, resource, or endpoint doesn’t exist
413Payload Too LargeFile exceeds size limit
415Unsupported Media TypeFile type not supported
422Validation ErrorParameters are present but invalid
429Rate LimitedToo many requests — see Rate Limits
500Internal ErrorServer-side error — retry or contact support
503Service UnavailableAll workers busy — retry with backoff

​
Error Codes

​
Authentication

CodeHTTPMessageResolution
UNAUTHORIZED401Invalid API secretCheck your api-secret header value. Get a valid secret from Developer → API Keys.
MISSING_AUTH401Missing api-secret headerAdd api-secret header to your request.
ACCOUNT_SUSPENDED401Account suspendedContact support via Discord.
INSUFFICIENT_BALANCE402Insufficient creditsTop up credits at www.bithuman.ai.

​
Agent Operations

CodeHTTPMessageResolution
AGENT_NOT_FOUND404Agent not foundCheck the agent code. Use POST /v1/validate to verify your API secret has access.
AGENT_PROCESSING409Agent is still generatingWait for generation to complete. Poll /v1/agent/status/{id}.
AGENT_FAILED400Agent generation failedCheck generation logs. Retry with different parameters.
VALIDATION_ERROR422prompt is requiredInclude all required fields. See endpoint documentation.
NO_ACTIVE_ROOMS404No active rooms for agentThe agent must be in an active LiveKit session for /speak and /add-context.

​
File Operations

CodeHTTPMessageResolution
FILE_TOO_LARGE413File exceeds size limitImages: 10 MB max. Videos: 100 MB max. Audio: 50 MB max.
UNSUPPORTED_TYPE415Unsupported file typeSupported: JPEG, PNG, WebP, MP4, WAV, MP3, OGG.
DOWNLOAD_FAILED400Could not download URLEnsure the URL is publicly accessible and returns a valid file.

​
Dynamics

CodeHTTPMessageResolution
DYNAMICS_NOT_FOUND404No dynamics for agentGenerate dynamics first with POST /v1/dynamics/generate.
DYNAMICS_PROCESSING409Dynamics still generatingWait for generation to complete.

​
Session & Infrastructure

CodeHTTPMessageResolution
RATE_LIMITED429Rate limit exceededBack off and retry. See Rate Limits.
NO_AVAILABLE_WORKERS503All workers busyRetry with exponential backoff (up to 5 times).
SESSION_LIMIT429Concurrent session limit reachedWait for an existing session to end, or upgrade your tier.
INTERNAL_ERROR500Internal server errorRetry once. If persistent, report via Discord.

​
Handling Errors in Python

import requests

resp = requests.post(
    "https://api.bithuman.ai/v1/agent/generate",
    headers={"api-secret": api_secret, "Content-Type": "application/json"},
    json={"prompt": "You are a helpful assistant"},
)

if resp.status_code == 200:
    result = resp.json()
    print(f"Agent {result['agent_id']} is generating...")

elif resp.status_code == 401:
    print("Invalid API secret. Check BITHUMAN_API_SECRET.")

elif resp.status_code == 429:
    print("Rate limited. Wait a moment and retry.")

elif resp.status_code == 503:
    print("Workers busy. Retry in a few seconds.")

else:
    error = resp.json().get("error", {})
    print(f"Error {error.get('code')}: {error.get('message')}")

​
GPU Container Errors

The self-hosted expression-avatar container returns its own error responses:
EndpointErrorResolution
GET /healthConnection refusedContainer not started or still initializing
GET /ready503 Not ReadyModel still loading (~50s cold start) or all session slots full
POST /launch401 UnauthorizedInvalid BITHUMAN_API_SECRET in container env
POST /launch400 No face detectedImage has no detectable face. Use a clear front-facing photo.
POST /launch503 No capacityAll session slots in use. Wait or add more containers.
For GPU container troubleshooting, see Self-Hosted GPU.