エラーコード
機械可読な版は errors.json にあります。
WebSocket のコード
unauthorized
- 対処: 新しいセッショントークン（Ingest は ingest:write、Subscribe は transcript:read）や有効な API キーを使う。
- WebSocket（Ingest・Subscribe）: 文字おこしくんが接続を切る。クライアントは、再接続しない。
- 起きたこと: クライアントが資格情報を送らなかった。または、送った資格情報が、不正か、期限切れか、失効している。または、トークンの権限（scope）が足りない。
- HTTP: 401「認証が必要です」（WWW-Authenticate: Bearer realm="mojiokoshi"）
protocol_version_unsupported
- 対処: hello の protocolVersion を 1 にする（クライアントを更新する）。
- WebSocket（Ingest・Subscribe）: 文字おこしくんが接続を切る。クライアントは、再接続しない。
- 起きたこと: hello の protocolVersion を文字おこしくんが扱えない。
invalid_message
- 対処: 送るメッセージを JSON Schema で検証して直す。fatal なら、文字おこしくんが hello を拒んだので、同じ hello で再接続しない。
- WebSocket（Ingest・Subscribe）: fatal なら、文字おこしくんが接続を切る。クライアントは、再接続しない。fatal でなければ、クライアントは接続を使い続ける。
- 起きたこと: クライアントが、JSON として読めないメッセージか、形式に違反するメッセージを送った。hello の前にほかのメッセージを送ったときと、hello が時間内（10 秒）に届かないときも、文字おこしくんはこのコードを送る。
unknown_track
- 対処: track_open でトラックを開いてから、その channel で音声を送り、その trackId で speech_start / speech_end を送る。
- WebSocket（Ingest）: 文字おこしくんは接続を切らない。クライアントは接続を使い続ける。
- 起きたこと: クライアントが、開いていない trackId か channel を参照した。
unknown_speaker
- 対処: speaker_upsert で話者を宣言してから、その話者の single トラックを track_open する。
- WebSocket（Ingest）: 文字おこしくんは接続を切らない。クライアントは接続を使い続ける。
- 起きたこと: クライアントが、speaker_upsert で宣言していない speakerId を参照した。たとえば、single トラックの speakerId が、宣言していない話者を指していた。
channel_in_use
- 対処: 使っていない channel 番号で track_open し直す（track_close した番号は再利用してよい）。
- WebSocket（Ingest）: 文字おこしくんは接続を切らない。クライアントは接続を使い続ける。
- 起きたこと: track_open で指定した channel を、同じ接続の別のトラックが使っている。
track_limit_exceeded
- 対処: 使っていないトラックを track_close してから、新しいトラックを開く。文字おこしくんが開かなかったトラックの音声は送らない。全部の API キーを合わせた上限に当たったときは、時間をおいてから、文字おこしくんが開かなかったトラックを開き直す。
- WebSocket（Ingest）: 文字おこしくんは接続を切らない。クライアントは接続を使い続ける。
- 起きたこと: トラックの数が、1 接続あたりの上限（64 本）を超えた。または、API キーで作ったセッションで開いているトラックの数が、全部の API キー（ほかの利用者のキーを含む）を合わせた上限を超えた。または、テナント（Discord サーバー）の同時トラック数が、文字おこしくんの運営者が付けた上限を超えた。公式の文字おこしくん（moji.kaitoranma.com）には、テナントの同時トラック数の上限は無い。
unsupported_format
- 対処: opus は 48000 Hz・1/2ch、pcm_s16le は 8000〜48000 Hz・1/2ch で track_open し直す。
- WebSocket（Ingest）: 文字おこしくんは接続を切らない。クライアントは接続を使い続ける。
- 起きたこと: track_open の format（コーデック・サンプルレート・チャンネル数）を文字おこしくんが扱えない。
rate_limited
- 対処: 送る量を減らす。HTTP では、Retry-After の秒数だけ待ってから要求をやり直す。WebSocket では、文字おこしくんが接続を切ったら、待ち時間をおいて再接続する。
- WebSocket（Ingest・Subscribe）: fatal なら、文字おこしくんが接続を切る。クライアントは、30 秒待って再接続する。fatal でなければ、クライアントは接続を使い続ける。
- 起きたこと: 送信量・要求数・接続数・話者数などが上限を超えた。または、Subscribe のクライアントの受信が、文字おこしくんからの送信に追いつかない。
- HTTP: 429「要求が多すぎます」（Retry-After、retryAfterSeconds、RateLimit / RateLimit-Policy）
session_ended
- 対処: 再接続しない。文字起こしを続けるなら、新しいセッションを作る。
- WebSocket（Ingest・Subscribe）: 文字おこしくんが接続を切る。クライアントは、再接続しない。
- 起きたこと: セッションが終了しているか、存在しない。保持期間を過ぎて消えたセッションにも、文字おこしくんはこのコードを送る。
- HTTP: 409「セッションは終了しています」
superseded
- 対処: 再接続しない。新しい接続のほうが有効になっている。1 セッションに、Ingest の送り手は 1 つだけにする。
- WebSocket（Ingest）: 文字おこしくんが接続を切る。クライアントは、再接続しない。
- 起きたこと: 同じセッションに新しい Ingest の接続が来たので、文字おこしくんがこの接続を新しい接続に置き換えた。
quota_exceeded
- 対処: 次の UTC 0 時（日本時間 9:00）の後に新しいセッションを作る。公式の文字おこしくん（moji.kaitoranma.com）には、1 日の利用量の上限は無い。上限を変えたいときは、文字おこしくんの運営者（contact@kaitoranma.com）に連絡する。
- WebSocket（Ingest）: 文字おこしくんが接続を切る。クライアントは、再接続しない。
- 起きたこと: テナント（Discord サーバー）の利用量が、今日（UTC）の利用上限に達した。Ingest では、セッションも終わっている。
- HTTP: 429「利用上限に達しました」（Retry-After（次の UTC 0 時までの秒数）、retryAfterSeconds、quota）
internal
- 対処: 指数バックオフ（ジッター付き）でやり直す。問題が続くなら、文字おこしくんの運営者（contact@kaitoranma.com）に連絡する。
- WebSocket（Ingest・Subscribe）: fatal なら、文字おこしくんが接続を切る。クライアントは、バックオフで再接続する。fatal でなければ、クライアントは接続を使い続ける。
- 起きたこと: 文字おこしくんの内部で問題が起きた。
- HTTP: 500「文字おこしくんの内部のエラーです」
HTTP だけのコード
forbidden
- 対処: 対象のセッションとテナントに合った資格情報を使う。
- 起きたこと: 要求に使ったトークンが、別のセッションのものだった。または、要求の tenantId か externalRef が、API キーのテナントと違っていた。
- HTTP: 403「この操作は許可されていません」
insufficient_scope
- 対処: 応答の requiredScope が示すスコープを持つ API キーを、Discord サーバーの管理者に管理画面で発行してもらう。
- 起きたこと: 要求に使った API キーに、その操作のスコープが無い。
- HTTP: 403「API キーの権限が足りません」（WWW-Authenticate（error="insufficient_scope", scope="…"）、requiredScope）
api_access_disabled
- 対処: 文字おこしくんの運営者（contact@kaitoranma.com）に連絡する。
- 起きたこと: このテナント（Discord サーバー）では、API キーの利用が止まっている。公式の文字おこしくん（moji.kaitoranma.com）では、文字おこしくんの運営者が止めたときだけ、この状態になる。
- HTTP: 403「API キーの利用が無効です」
invalid_json
- 対処: Content-Type: application/json で正しい JSON のオブジェクトを送る。
- 起きたこと: 文字おこしくんが、要求の本文を JSON として読めなかった。
- HTTP: 400「本文が JSON ではありません」
invalid_request
- 対処: detail が示すフィールドを直す。
- 起きたこと: 要求の値が不正だった。本文の形・クエリの形・パスの tenantId の形・Idempotency-Key の形のどれかが不正なときも、文字おこしくんはこのコードを返す。
- HTTP: 400「要求の値が不正です」
session_not_found
- 対処: sessionId を確かめる。消えた記録は戻らないので、残したい記録は保持期間の内に書き出す。
- 起きたこと: 指定したセッションが無い。保持期間を過ぎて消えたセッションを指定したときと、API キーのテナントとは別のテナントのセッションを指定したときにも、文字おこしくんはこのコードを返す。
- HTTP: 404「セッションが見つかりません」
session_active
- 対処: POST /v1/sessions/:id/end でセッションを終えてから削除する。終了の途中なら、少し待ってから削除をやり直す。
- 起きたこと: クライアントが、稼働中か終了の途中のセッションを削除しようとした。
- HTTP: 409「セッションは終了していません」
idempotency_in_progress
- 対処: Retry-After の秒数だけ待ってから、同じキーと同じ本文で要求をやり直す。
- 起きたこと: 同じ Idempotency-Key の前の要求を、文字おこしくんがまだ処理している。
- HTTP: 409「同じ Idempotency-Key の要求を処理中です」（Retry-After: 1）
idempotency_mismatch
- 対処: 別の操作には新しい Idempotency-Key を使う。
- 起きたこと: クライアントが、前の要求と同じ Idempotency-Key で、本文の違う要求を送った。
- HTTP: 422「この Idempotency-Key は、本文の違う要求で使用済みです」
not_found
- 対処: パスを確かめる。API のパスは /v1 から始まる。
- 起きたこと: 要求したパスの API が無い。
- HTTP: 404「見つかりません」
method_not_allowed
- 対処: リファレンス（openapi.yaml）が示すメソッドを使う。
- 起きたこと: そのパスでは、要求したメソッドを使えない。
- HTTP: 405「このメソッドは使えません」
payload_too_large
- 対処: 要求の本文を小さくする。
- 起きたこと: 要求の本文が 16 KiB を超えた。
- HTTP: 413「本文が大きすぎます」
upgrade_required
- 対処: WebSocket（wss://）でつなぐ。
- 起きたこと: クライアントが、WebSocket のパス（/v1/ingest・/v1/subscribe）に普通の HTTP でアクセスした。
- HTTP: 426「WebSocket で接続してください」（Upgrade: websocket）
too_many_connections
- 対処: 普通の切断と同じく指数バックオフで再接続する。使っていない接続を閉じる。
- 起きたこと: WebSocket の同時接続数が、上限（文字おこしくんの API 全体で 4,096、同じ送信元から 1,024）を超えた。文字おこしくんは、upgrade の要求への HTTP の応答でこのコードを返す。
- HTTP: 503 / 429「接続が多すぎます」（API 全体の上限は 503、同じ送信元の上限は 429）
shutting_down
- 対処: バックオフしてから、要求をやり直す。文字おこしくんが再起動した後は、要求が通る。
- 起きたこと: 再起動かデプロイのために、文字おこしくんは停止の途中だった。
- HTTP: 503「文字おこしくんは停止の途中です」
使わなくなったコード
文字おこしくんは、この節のコードを、今は返しません。クライアントは、このコードを扱う処理を残しておいても、消しても構いません。
credits_exhausted
- 使わなくなったコード: 文字おこしくんは、2026-10-14 から、このコードを返さない。
- 対処: 対処は要らない。古いクライアントは、このコードを扱う処理を残しておいてよい。
- 起きたこと: 以前、Discord サーバーのクレジットが残っていないときに返していたコード。文字おこしくんは、2026-10-14 から、このコードを返さない。
- HTTP: 402「クレジットが残っていません」
一覧
| code | WebSocket の接続 | HTTP |
|---|---|---|
unauthorized |
文字おこしくんが切り、クライアントは再接続しない | 401 |
protocol_version_unsupported |
文字おこしくんが切り、クライアントは再接続しない | — |
invalid_message |
fatal なら文字おこしくんが切り、クライアントは再接続しない | — |
unknown_track |
文字おこしくんは切らない | — |
unknown_speaker |
文字おこしくんは切らない | — |
channel_in_use |
文字おこしくんは切らない | — |
track_limit_exceeded |
文字おこしくんは切らない | — |
unsupported_format |
文字おこしくんは切らない | — |
rate_limited |
fatal なら文字おこしくんが切り、クライアントは 30 秒待って再接続する | 429 |
session_ended |
文字おこしくんが切り、クライアントは再接続しない | 409 |
superseded |
文字おこしくんが切り、クライアントは再接続しない | — |
quota_exceeded |
文字おこしくんが切り、クライアントは再接続しない | 429 |
internal |
fatal なら文字おこしくんが切り、クライアントはバックオフで再接続する | 500 |
forbidden |
— | 403 |
insufficient_scope |
— | 403 |
api_access_disabled |
— | 403 |
invalid_json |
— | 400 |
invalid_request |
— | 400 |
session_not_found |
— | 404 |
session_active |
— | 409 |
idempotency_in_progress |
— | 409 |
idempotency_mismatch |
— | 422 |
not_found |
— | 404 |
method_not_allowed |
— | 405 |
payload_too_large |
— | 413 |
upgrade_required |
— | 426 |
credits_exhausted（使わなくなった） |
— | 402 |
too_many_connections |
— | 503 / 429 |
shutting_down |
— | 503 |
クライアントは、未知のコードも受け入れ、error.fatal に従う。fatal な未知のコードでは、クライアントは internal と同じくバックオフで再接続する。HTTP では、クライアントは未知のコードをステータスで扱う（5xx と 429 は待ってやり直し、それ以外の 4xx はやり直さない）。
クライアントがいつ再接続し、いつ再接続せずに終えるかは再接続とエラーの扱いに、HTTP のエラーの形は HTTP API リファレンスにあります。
公式のアプリだけが受け取るコード
文字おこしくんは、公式のアプリ（管理画面と Discord アクティビティ）と文字おこしくんの運営者だけが使う操作に、この節のコードを返します。
key_not_found
- 対処: keyId を確かめる。
- 起きたこと: 指定した API キーが無いか、別のテナントのものだった。
- HTTP: 404「API キーが見つかりません」
webhook_not_found
- 対処: webhookId を確かめる。
- 起きたこと: 指定した Webhook の送信先が無いか、別のテナントのものだった。
- HTTP: 404「Webhook の送信先が見つかりません」
webhook_delivery_not_found
- 対処: deliveryId と webhookId の組を確かめる。
- 起きたこと: 指定した送信の記録がその送信先に無い。終わった送信の記録は 7 日で削除される。削除された記録を指定したときにも、文字おこしくんはこのコードを返す。
- HTTP: 404「Webhook の送信の記録が見つかりません」
key_limit_exceeded
- 対処: 使っていないキーを管理画面で取り消してから、新しいキーを作る。
- 起きたこと: テナントの有効な API キーの数が、上限（既定 25 個）に達した。
- HTTP: 409「API キーの数が上限に達しています」（limit）
webhook_limit_exceeded
- 対処: 使っていない送信先を管理画面で削除してから、新しい送信先を追加する。
- 起きたこと: テナントの Webhook の送信先の数が上限（既定 5 個）に達した。
- HTTP: 409「Webhook の送信先の数が上限に達しています」（limit）
activity_not_configured
- 対処: あなたの側では直せない（原因は、文字おこしくんの運営者の側の設定にある）。問題が続くときは、文字おこしくんの運営者に連絡する。
- 起きたこと: 文字おこしくんは、Discord アクティビティ専用の操作にだけ、このコードを返す。文字おこしくんのサーバーに、アクティビティの設定が無い。
- HTTP: 503「アクティビティの設定がありません」
invalid_grant
- 対処: アクティビティを開き直して認可をやり直す。
- 起きたこと: 文字おこしくんは、Discord アクティビティ専用の操作にだけ、このコードを返す。クライアントが送った OAuth2 の認可コードが、不正か、期限切れか、使用済みだった。
- HTTP: 400「認可コードが無効です」
not_in_channel
- 対処: ボイスチャンネルに入ってから、アクティビティを開く。
- 起きたこと: 文字おこしくんは、Discord アクティビティ専用の操作にだけ、このコードを返す。要求した人が、アクティビティを開いた Discord サーバーのどのボイスチャンネルにもいない。要求した人がボイスチャンネルにいるかを確かめられないときも、文字おこしくんはこのコードを返す。
- HTTP: 403「ボイスチャンネルにいません」
no_active_session
- 対処: 誰かが /start を実行して、文字起こしが始まるのを待つ。
- 起きたこと: 文字おこしくんは、Discord アクティビティ専用の操作にだけ、このコードを返す。要求した人が今いるボイスチャンネルで、文字起こしが動いていない。
- HTTP: 404「稼働中のセッションがありません」
discord_unavailable
- 対処: 少し待ってから、要求をやり直す。
- 起きたこと: 文字おこしくんは、Discord アクティビティ専用の操作にだけ、このコードを返す。Discord の障害か上限のために、文字おこしくんが Discord の API に問い合わせられない。
- HTTP: 502「Discord に接続できません」