Errors

The DialogBrain API returns structured error responses that help you diagnose and fix problems.

Error Format

Simple Errors (400, 401, 403, 404, 409, 429, 502, 503)

Most errors are returned as a simple JSON object with a detail field:

{
  "detail": "Human-readable description of what went wrong"
}

Validation Errors (422 Unprocessable Entity)

When a request has invalid data (e.g., missing required fields), the API returns a 422 with detailed field-level errors:

{
  "detail": [
    {
      "loc": ["body", "agent_id"],
      "msg": "field required",
      "type": "value_error.missing"
    },
    {
      "loc": ["body", "prompt_text"],
      "msg": "ensure this value has at least 10 characters",
      "type": "value_error.string.too_short"
    }
  ]
}

Common Status Codes

Status	Meaning	Example
400	Invalid request (missing required fields, invalid data)	Missing Idempotency-Key on a POST /agents
401	Missing or invalid API key	{"detail": "Invalid or revoked API key"}
403	Access denied (voice disabled, permission denied)	Attempting to create a call without voice enabled
404	Resource not found	{"detail": "Agent 999999 not found"}
409	Conflict (duplicate idempotency key, request in progress)	Same idempotency key with different body
422	Validation error (invalid request body)	Missing required fields in agent creation
429	Rate limited	Too many requests in a short time
502	Bad gateway (typically during call creation, backend issue)	Temporary service issue
503	Service unavailable (recording URL generation fails)	Recording storage unavailable

Real Error Examples

401 Unauthorized

curl https://api.dialogbrain.com/api/v1/agents \
  -H "X-API-Key: db_live_invalid"

Response:

{
  "detail": "Invalid or revoked API key"
}

404 Not Found

curl https://api.dialogbrain.com/api/v1/agents/999999 \
  -H "X-API-Key: db_live_YOUR_KEY"

Response:

{
  "detail": "Agent 999999 not found"
}

307 / 503 on the recording route (Recording Unavailable)

When retrieving a recording URL and storage cannot mint a URL:

curl https://api.dialogbrain.com/api/v1/calls/5c8d7f2a9e1b3c4d/recording \
  -H "X-API-Key: db_live_YOUR_KEY"

Possible responses:

1. 307 Temporary Redirect (recording is available):

   HTTP/1.1 307 Temporary Redirect
   Location: https://storage.example.com/recording.wav?expires=...

   Redirect to the actual recording URL. Append ?redirect=true to get a JSON response instead of a redirect.

2. 503 Service Unavailable (recording storage is down):

   {
     "detail": "Recording storage is temporarily unavailable"
   }

Handling Errors in Code

With curl

Check the HTTP status code:

response=$(curl -s -w "%{http_code}" \
  -H "X-API-Key: db_live_YOUR_KEY" \
  https://api.dialogbrain.com/api/v1/agents/42)

if [[ $response == *"401"* ]]; then
  echo "Invalid API key"
fi

With Python SDK

The SDK raises exceptions for non-2xx responses:

from dialogbrain import DialogBrainClient
from dialogbrain.exceptions import APIError, NotFoundError

async with DialogBrainClient(api_key="db_live_YOUR_KEY") as client:
    try:
        agent = await client.agents.get(999999)
    except NotFoundError as e:
        print(f"Agent not found: {e.detail}")
    except APIError as e:
        print(f"API error: {e.status_code} - {e.detail}")

---

See also: Idempotency, Pagination