エラーと制限｜voicast ドキュメント

エラーの形#

json

{
  "error": "invalid_config",
  "message": "config に誤りがあります",
  "details": ["fields[0].key は英小文字・数字・_（先頭は英字）", "closing は空でない文字列"],
  "request_id": "req_…"
}

分岐には error（エラーの種類）を使います。message は人が読むための説明で、文言は変わることがあります。
details は入力の誤り（422）のときに、項目ごとの誤りを並べます。
request_id は呼び出しの ID です。成功・失敗にかかわらず、すべての応答の x-request-id にも入ります。問い合わせのときに伝えてください。

状態コード#

HTTP	内容
400	本文が JSON でない
401	API キーが無い・違う・取り消し済み
402	料金の都合で、新しい通話を断っている
403	権限が足りない
404	見つからない（ほかの環境のものも見つからない扱い）
409	今の状態とぶつかる（重複・使用中など）
422	入力の誤り
429	回数の上限を超えた
500	voicast の中のエラー
503	外のサービス（決済・連携先・Webhook の送信）に届かない、まだ設定されていない

エラーの種類#

HTTP	`error`	内容	直し方
400	`invalid_json`	本文が JSON のオブジェクトでない	`Content-Type: application/json` で JSON のオブジェクトを送る
401	`unauthorized`	API キーが無い・違う・取り消し済み	`Authorization: Bearer vk_…` を確かめる
402	`balance_depleted`	残高が 0 以下（チャージ式）	チャージするか、オートチャージを使う
402	`payment_overdue`	請求書の支払い期限から 14 日たった（請求書払い）	請求書を払う（払われればすぐ戻る）
402	`spending_cap_reached`	今月の見込みが使いすぎの上限に届いた（請求書払い）	管理画面で上限を上げる
403	`forbidden`	役割が足りない・ブラウザからの MCP の呼び出し	組織の owner か admin に役割を上げてもらう
404	`not_found`	ID が無い、ほかの環境のもの	一覧で ID を確かめる。テストと本番のキーを取り違えていないか
409	`conflict`	同じ `external_id` のテナントがある	既存のテナントを使う
409	`in_use`	会話の設定をテナントが使っている	テナントの `agent_id` を替えてから消す
409	`tenant_disabled`	テナントが止まっている	`PATCH /v1/tenants/{id}` で `status: active` にする
409	`needs_reauth`	連携が切れている	連携の画面でもう一度つなぐ
422	`invalid_request`	入力の誤り	`message`・`details` を見て直す
422	`invalid_config`	会話の設定・連携の設定の誤り	`details` の項目を直す
422	`no_agent`	使う会話の設定が決まらない	`agent_id` を渡すか、テナントに設定する
422	`verify_failed`	連携の保存の前の試しの呼び出しに失敗した	URL・API キーを確かめる
422	`connect_failed`	連携を始められない（MCP サーバーのメタデータを読めないなど）	URL と相手の対応を確かめる
429	`rate_limited`	回数の上限を超えた	少し待ってから送り直す
500	`internal`	voicast の中のエラー	少し待ってから送り直す。続くときはお問い合わせください
503	`unavailable`	外のサービスに届かない・設定がまだ	少し待ってから送り直す

通話を断るとき#

料金の都合で新しい通話を断るとき（402）は、経路ごとに次のように見えます。始まっている通話は切りません。

経路	見え方
Web・アプリ	`POST /v1/sessions` が 402。セッションを作ってからつなぐまでに断ることになったときは、`webrtc_url` への offer が 403（いずれ 402 にそろえる予定です。403 も 402 も「つなげない」として扱ってください）
電話	音声サーバーがすぐに接続を閉じ、Twilio は `action` か次の動詞へ進む。通話の記録は作られない

回数の上限#

対象	上限
`/v1` の API と、API キーでの MCP の呼び出し	API キーごとに 1 分 600 回（合わせて数える）
MCP（ログインでの呼び出し）	1 人あたり 1 分 300 回
MCP のクライアントの登録	接続元ごとに 1 時間 30 回
ログインのメール	同じメールアドレスへ 1 時間 5 回

/v1 の応答には、x-ratelimit-limit（1 分の上限）・x-ratelimit-remaining（残り）・x-ratelimit-reset（枠の終わり、Unix 秒）が付きます。上限を超えると 429 rate_limited と Retry-After（待つ秒数）を返すので、その秒数だけ待ってから送り直します（SDK は自動で送り直します）。

長さと時間の上限#

対象	上限
`client_token`（Web・アプリ）	2 分・1 回だけ
連携の画面のリンク・Webhook の設定画面のリンク	15 分
接続の鍵・道具の署名の鍵を作り直したあと	古い鍵も 24 時間通る
通話中の道具の応答	8 秒まで待つ。応答の JSON は 4,000 文字まで AI に渡す
連携の操作	3 秒で打ち切る
会話の設定	聞き取る項目 20 個・よくある質問 50 個・道具 10 個・連携 10 個（会話の設定）
`GET /v1/calls`	1 回 100 件まで（既定 50）
`GET /v1/usage`	期間は 366 日まで
文字起こし	500 発言まで・1 発言 2,000 文字まで
テナントの `external_id`	英数字と `. _ : -` の 1〜100 文字
名前（会話の設定・テナント）	100 文字まで