# Error Responses

The API uses standard HTTP status codes and returns error details in JSON format.

## 401 Unauthorized

Invalid or missing API token:

```json
{
  "success": false,
  "message": "Unauthorized"
}
```

## 400 Bad Request - OTP Validation

Voice must have at least one dynamic part with digit mode:

```json
{
  "success": false,
  "message": "Voice must have at least one dynamic part with digit mode for OTP broadcast"
}
```

## 400 Bad Request - Duplicate Numbers

Duplicate phone numbers found in the request:

```json
{
  "success": false,
  "message": "Duplicate phone number found",
  "duplicated_number": "019XXXXXXXX"
}
```

## 400 Bad Request - Audio Validation Failed

Direct broadcast audio must be G.711-compatible (WAV, 8000 Hz, mono, `pcm_s16le`). Each failed URL is listed:

```json
{
  "success": false,
  "message": "Audio file validation failed. Files must be in G.711-compatible format (WAV, 8000Hz, Mono, pcm_s16le)",
  "errors": [
    {
      "field": "voices[0]",
      "url": "https://cdn.example.com/audio/announcement.wav",
      "issue": "Invalid sample rate. Expected: 8000Hz, Found: 44100Hz"
    }
  ]
}
```

## 402 Payment Required

Insufficient balance to process the broadcast:

```json
{
  "success": false,
  "message": "Insufficient balance"
}
```

## 403 Forbidden

Voice not found, not approved, or sender not active:

```json
{
  "success": false,
  "message": "Voice not found or not approved"
}
```

## 409 Conflict

Duplicate request - request_id already used within 15 minutes:

```json
{
  "success": false,
  "message": "Request already processed"
}
```

## 404 Not Found

Broadcast or survey not found or access denied:

```json
{
  "success": false,
  "message": "Broadcast not found"
}
```

## 500 Internal Server Error

Server error occurred while processing the request:

```json
{
  "success": false,
  "message": "Failed to create OTP broadcast"
}
```

## Call Center Errors

Call-center SDK routes and `GET /api/cc/agents/:agent_id/calls` return `{ "error", "code" }` rather than `{ "success": false, "message" }`.

### 401 Unauthorized - Invalid SDK Token

`POST /api/sdk/session` when the token is missing, already used, or expired:

```json
{
  "error": "invalid or expired token",
  "code": "token_invalid"
}
```

### 403 Forbidden - Agent Inactive

Agent is not active (when creating a token) or was deactivated after the token was created (when connecting):

```json
{
  "error": "agent not active",
  "code": "agent_inactive"
}
```

### 403 Forbidden - Origin Not Allowed

`POST /api/sdk/session` when the page is not on HTTPS, or its hostname is not on your Call SDK allowed-domain list (and test mode is off):

```json
{
  "error": "origin not allowed for this account",
  "code": "origin_not_allowed"
}
```

### 404 Not Found - Agent Not Found

`POST /api/sdk/token`, `DELETE /api/sdk/session`, and `GET /api/cc/agents/:agent_id/calls` when `agent_id` does not belong to your account:

```json
{
  "error": "agent not found",
  "code": "agent_not_found"
}
```

## Survey-Specific Errors

### 403 Forbidden - Template Not Found

Survey template not found or not in published status:

```json
{
  "success": false,
  "message": "Template not found or not published"
}
```

### 403 Forbidden - Sender Not Found

Sender number not found or not active:

```json
{
  "success": false,
  "message": "Sender not found or not active"
}
```