AI Voice Agent Errors and Security

AI Voice Agent APIs use the standard MiniVoice bearer API key. The API key scopes every request to one customer. Do not send customer_id in public AI requests; the public create and update handlers reject unsupported configuration fields.

Authentication

curl -sS https://api.minivoice.eu/v1/ai/agents \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY'

Missing or invalid authentication returns the standard unauthorized response for customer AI routes.

{
  "error": {
    "code": "unauthorized",
    "message": "unauthorized"
  }
}

Common Error Codes

Code	HTTP status	Meaning
`invalid_json`	`400`	Request body was not valid JSON.
`unsupported_field`	`400`	Request included an internal or unsupported field.
`invalid_ai_agent`	`400`	Agent validation failed.
`invalid_model`	`400`	Model is not in the public allowlist.
`invalid_voice`	`400`	Voice is not in the public allowlist.
`ai_agent_not_found`	`404`	Agent was not found for the authenticated customer.
`agent_id_required`	`400`	Outbound AI call was missing `agent_id`.
`ai_agent_not_available`	`400`	Agent does not exist, does not belong to the customer, or is inactive.
`invalid_to`	`400`	`to` is not a valid E.164 number.
`invalid_from`	`400`	`from` is missing, invalid, or not owned by the customer.
`insufficient_balance`	`402`	Customer balance is too low to create an AI call.
`concurrent_call_limit_reached`	`429`	Customer concurrent call limit was exceeded.
`cps_limit_reached`	`429`	Customer calls-per-second limit was exceeded.
`no_active_trunk`	`400`	No active outbound trunk is configured.
`originate_failed`	`502`	Outbound originate failed before answer.

Validation Limits

Field	Limit
`name`	Required on create, at most 120 characters.
`greeting`	At most 500 characters.
`instructions`	At most 8000 characters.
`description`	At most 1000 characters.
`fallback_message`	At most 500 characters.
`hangup_tool_description`	At most 1000 characters.
`transfer_tool_description`	At most 1000 characters.
`max_turns`	`1` to `20`.
`max_call_seconds`	`30` to `1800`.
`silence_timeout_ms`	`1000` to `15000`.
`turn_recording_max_seconds`	`2` to `30`.
`max_turn_latency_ms`	`1000` to `60000`.
outbound call `context`	JSON object, at most 4096 bytes before storage wrapping.
`transfer_destinations`	At most 10 destinations.

Unsupported Field Example

curl -sS https://api.minivoice.eu/v1/ai/agents \
  -X POST \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "cust_123",
    "name": "Bad Request"
  }'

{
  "error": {
    "code": "unsupported_field",
    "message": "unsupported AI agent field"
  }
}

Security Guidance

Store API keys server-side. Do not place MiniVoice API keys in browsers, mobile apps, or public repositories. Verify webhook signatures before parsing webhook JSON. For outbound AI calls, pass only the context needed for the conversation and keep it under the documented size limit.

Testing

Add negative API tests for invalid JSON, invalid model, invalid voice, paused agent usage, missing balance, invalid from, and oversized context. Your client should preserve the MiniVoice error.code because it is more stable for branching than the human-readable message.

Authentication​

Common Error Codes​

Validation Limits​

Unsupported Field Example​

Security Guidance​

Testing​