ページの一覧

ドキュメント

エラーと制限

voicast の API が返すエラーの形・状態コード・エラーの種類と、回数・長さ・時間の上限。

Markdown で見る

エラーの形#

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 の送信)に届かない、まだ設定されていない、データベースが一時的に使えない(Retry-After の秒数だけ待つ)

エラーの種類#

HTTP error 内容 直し方
400 invalid_json 本文が JSON のオブジェクトでない Content-Type: application/json で JSON のオブジェクトを送る
401 unauthorized API キーが無い・違う・取り消し済み Authorization: Bearer vk_… を確かめる
402 balance_depleted 残高が 0 以下 チャージするか、オートチャージを使う
403 forbidden ロールが足りない・ブラウザからの MCP の呼び出し 組織の owner か admin にロールを上げてもらう
404 not_found ID が無い、ほかの環境のもの 一覧で ID を確かめる。テストと本番のキーを取り違えていないか
409 conflict 同じ external_id のテナントがある 既存のテナントを使う
409 in_use エージェント設定をテナントか SIP の接続情報が使っている テナントの agent_id を替え、SIP の接続情報は 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・ヘッダーの名前の誤りなど) message を見て、URL とヘッダーの名前を直す
429 rate_limited 回数の上限を超えた 少し待ってから送り直す
500 internal voicast の中のエラー 少し待ってから送り直す。続くときはお問い合わせください
503 unavailable 外のサービスに届かない・設定がまだ・データベースが一時的に使えない Retry-After の秒数(あれば)だけ待ってから送り直す。数を足す操作は、送り直すと 2 重に反映されることがある

会話を断るとき#

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

経路 見え方
Web・アプリ POST /v1/sessions が 402。セッションを作ってからつなぐまでに断ることになったときは、webrtc_url への offer も同じ 402 と error: "balance_depleted"(トークンの期限切れ・使用済みは 403)
電話 音声サーバーがすぐに接続を閉じ、Twilio は action か次の動詞へ進む。会話記録は作られない

混み合っているとき#

音声サーバーの同時の会話が上限に達しているときは、新しい会話を始めずに断ります。話し中の会話の声が届かなくなるのを防ぐためで、始まっている会話は切りません。少し待てばつながります。

経路 見え方
Web・アプリ webrtc_url への offer が 503 と error: "busy"、Retry-After: 30。トークンは使われていないので、同じトークンでつなぎ直せます(期限内なら)。SDK(voicast/web)では VoiceSessionError の status が 503、code が busy
電話 音声サーバーがすぐに接続を閉じ、Twilio は action か次の動詞へ進む。会話記録は作られない(電話でつなぐのとおり人へ転送できます)

回数の上限#

対象 上限
/v1 の API API キーごとに 1 分 600 回
MCP 1 人あたり 1 分 300 回
MCP のクライアントの登録 接続元ごとに 1 時間 30 回
ツールを試す呼び出し(POST /v1/tools/try・try_tool・管理画面の[試す]) 環境ごとに 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 秒まで待つ。応答の本文は 4,000 文字まで AI に渡す
連携の操作 3 秒で打ち切る
エージェント設定 聞き取る項目 20 個・よくある質問 50 個・ツール 10 個・連携 10 個(エージェント設定)
GET /v1/calls 1 回 100 件まで(既定 50)
GET /v1/usage 期間は 366 日まで
会話の記録と録音の保存期間 1・7・14・30 日(初期値 30 日。保存期間)
文字起こし 500 発言まで・1 発言 2,000 文字まで
テナントの external_id 英数字と . _ : - の 1〜100 文字
名前(エージェント・テナント) 100 文字まで