Errors and limits
The error format, status codes and error codes returned by the voicast API, and its rate, size and time limits.
Error format#
json
{
"error": "invalid_config",
"message": "config に誤りがあります",
"details": ["fields[0].key は英小文字・数字・_(先頭は英字)", "closing は空でない文字列"],
"request_id": "req_…"
}- Branch on
error(the error code).messageis a human-readable explanation, currently in Japanese, and its wording may change. - On validation errors (422),
detailslists one entry per problem. request_ididentifies the request. Every response, successful or not, also has it inx-request-id. Quote it when contacting support.
Status codes#
| HTTP | Meaning |
|---|---|
| 400 | The body is not JSON |
| 401 | The API key is missing, wrong or revoked |
| 402 | New calls are refused for billing reasons |
| 403 | Not allowed |
| 404 | Not found (including resources in another environment) |
| 409 | Conflicts with the current state (duplicate, in use and so on) |
| 422 | Invalid input |
| 429 | Rate limit exceeded |
| 500 | An internal error in voicast |
| 503 | An external service (payments, a connected provider, webhook delivery) is unreachable or not configured, or the database is temporarily unavailable (wait for Retry-After seconds) |
Error codes#
| HTTP | error |
Meaning | What to do |
|---|---|---|---|
| 400 | invalid_json |
The body is not a JSON object | Send a JSON object with Content-Type: application/json |
| 401 | unauthorized |
The API key is missing, wrong or revoked | Check Authorization: Bearer vk_… |
| 402 | balance_depleted |
The balance is zero or below | Top up, or turn on auto-recharge |
| 403 | forbidden |
Your role is not enough, or MCP was called from a browser | Ask an owner or admin for a higher role |
| 404 | not_found |
No such ID, or it belongs to another environment | Check the ID with a list call; make sure you are not mixing test and live keys |
| 409 | conflict |
A tenant with the same external_id exists |
Use the existing tenant |
| 409 | in_use |
Tenants or SIP credentials still use this agent | Change the tenants' agent_id, and change or delete the SIP credentials, first |
| 409 | tenant_disabled |
The tenant is disabled | Set status: active with PATCH /v1/tenants/{id} |
| 409 | needs_reauth |
The connection is broken | Sign in again under Connections in the dashboard |
| 422 | invalid_request |
Invalid input | See message and details |
| 422 | invalid_config |
Invalid agent or connection config | Fix the items in details |
| 422 | no_agent |
No agent could be determined | Pass agent_id or set one on the tenant |
| 422 | verify_failed |
The check before saving a connection failed (for example, an invalid URL or header name) | Read message and fix the URL or header name |
| 429 | rate_limited |
Rate limit exceeded | Wait a moment and retry |
| 500 | internal |
An internal error | Wait a moment and retry. Contact us if it persists |
| 503 | unavailable |
An external service is unreachable or not configured, or the database is temporarily unavailable | Wait for Retry-After seconds (if present) and retry. An operation that adds to a count may be applied twice if retried |
When calls are refused#
When new calls are refused for billing reasons (402), each channel sees it differently. Calls already in progress are never cut off.
| Channel | What you see |
|---|---|
| Web and apps | POST /v1/sessions returns 402. If the refusal starts between creating the session and connecting, the offer to webrtc_url returns the same 402 with error: "balance_depleted" (an expired or used token returns 403) |
| Phone | The voice server closes the stream immediately and Twilio moves on to action or the next verb. No call record is created |
When the voice server is busy#
When the voice server has reached its limit of concurrent calls, it refuses new calls instead of starting them. This keeps the audio of calls in progress from dropping out; calls already in progress are never cut off. Try again shortly.
| Channel | What you see |
|---|---|
| Web and apps | The offer to webrtc_url returns 503 with error: "busy" and Retry-After: 30. The token is not used, so you can reconnect with the same token while it is valid. With the SDK (voicast/web), VoiceSessionError has status 503 and code busy |
| Phone | The voice server closes the stream immediately and Twilio moves on to action or the next verb. No call record is created (transfer to a person as in Phone) |
Rate limits#
| Applies to | Limit |
|---|---|
The /v1 API |
600 requests per minute per API key |
| MCP | 300 calls per minute per user |
| MCP client registration | 30 per hour per source address |
Trying tools (POST /v1/tools/try, try_tool, Try in the dashboard) |
30 per minute per environment |
| Sign-in emails | 5 per hour per email address |
/v1 responses carry x-ratelimit-limit (the per-minute limit), x-ratelimit-remaining and x-ratelimit-reset (end of the window, Unix seconds). Over the limit you get 429 rate_limited with Retry-After (seconds to wait); wait that long and retry (the SDK does this for you).
Size and time limits#
| Item | Limit |
|---|---|
client_token (Web and apps) |
2 minutes, single use |
| Webhook-portal links | 15 minutes |
| After rotating a connection secret or the tools signing secret | The old one keeps working for 24 hours |
| Tool responses | voicast waits 8 seconds; up to 4,000 characters of the body reach the AI |
| Connection actions | Cut off after 3 seconds |
| Agents | 20 fields, 50 FAQ entries, 10 tools, 10 connections (Agents) |
GET /v1/calls |
Up to 100 per page (default 50) |
GET /v1/usage |
Periods up to 366 days |
| Retention period for call records and recordings | 1, 7, 14 or 30 days (30 by default; Retention) |
| Transcripts | Up to 500 turns, 2,000 characters each |
Tenant external_id |
1–100 characters: letters, digits and . _ : - |
| Names (agents, tenants) | Up to 100 characters |