Error Responses

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

401 Unauthorized

Invalid or missing API token:

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

400 Bad Request - OTP Validation

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

{
  "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:

{
  "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:

{
  "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:

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

403 Forbidden

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

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

409 Conflict

Duplicate request - request_id already used within 15 minutes:

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

404 Not Found

Broadcast or survey not found or access denied:

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

500 Internal Server Error

Server error occurred while processing the request:

{
  "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:

{
  "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):

{
  "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):

{
  "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:

{
  "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:

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

403 Forbidden - Sender Not Found

Sender number not found or not active:

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