エラーコード

このページは、ExpTech API を呼び出すときに起こりうるエラーをまとめたものです。エラーの内容は発生元によって違います。認証とクォータの失敗には本文がなく、OAuth2 は JSON を返し、SSE 配信はプレーンテキストまたは配信イベントを返します。先にステータスコードを見て、本文を解析するかどうかを決めてください。

HTTP ステータスコード

ステータスコード	発生元	条件	レスポンス本文	推奨する対処
302	データ API	一部の API は query を標準の書き方に直してからリダイレクトします（各エンドポイントの説明を参照）	リダイレクト	リダイレクトに従います（`curl -L`。`fetch` は既定で従います）
304	データ API	`If-None-Match` を付け、データが変わっていない	なし	キャッシュをそのまま使います
400	データ API	パラメータの誤り（400 を返すかは各エンドポイントの説明にあります）	エンドポイントによる	パラメータを修正します
400	SSE	`topics` がない、または topic 名が存在しない	プレーンテキスト	topic 名を修正します
400	OAuth2	OAuth2 のエラーを参照	JSON	リクエストを修正します
401	token が必要な HTTP API	`X-Api-Token` がない、または token が無効・取り消し済み	なし	header 名と token を確認します
401	SSE	token が無効または取り消し済み（`invalid token`）。権限が必要な topic に token がない（`unauthorized`）	プレーンテキスト	token を確認します
401	OAuth2	client の認証失敗（JSON の `invalid_client`）。`userinfo` の token が無効（本文なし）	JSON またはなし	client の設定または token を確認します
403	token が必要な HTTP API	token にその権限がない。アカウントがそのリソースを購読していない。サーバーが一時的にクォータ情報を取得できない	なし	権限と購読を確認します
403	SSE	`forbidden: token scope missing`、`forbidden: not subscribed`	プレーンテキスト	権限と購読を確認します
403	OAuth2	`too_many_tokens`：ユーザーの token が 25 個に達している	JSON	ユーザーに不要な token の削除を依頼します
404	すべて	パスが存在しない。データが存在しない（各エンドポイントの説明を参照）。指定したノードにそのルートがない（サーバーと Base URLを参照）	なし、または HTML ページ	パスと host を確認します
405	SSE、権限一覧	GET 以外のメソッド	SSE：`method not allowed`。権限一覧：なし	GET を使います
429	token が必要な HTTP API	今日のクォータを使い切った	なし	台北時間 00:00 以降に再試行するか、プランを上げます
429	SSE	権限が必要な topic がクォータ超過（`quota exceeded`）	プレーンテキスト	同上。約 60 秒以内の再接続も拒否されます
429	OAuth2	同じ IP から OAuth2 エンドポイントを呼び出しすぎ（毎秒約 4 回、短時間なら 5 回まで）	HTML ページ	頻度を下げて再試行します
500	OAuth2、データ API	サーバー内部エラー	JSON、またはエンドポイントによる	しばらくして再試行します
502、503、504	すべて	サーバーまたは上流が一時的に応答できない	HTML ページのことがあります	host を変えるか、しばらくして再試行します。サーバーと Base URLを参照
503	SSE	認証サービスに一時的に接続できない（`auth service unavailable`）。かつ、このリクエストが権限の必要な topic を要求している	プレーンテキスト	しばらくして再接続します

認証とクォータの失敗（本文なし）

token が必要な HTTP API の認証に失敗したときは、ステータスコードだけで、JSON もなく、WWW-Authenticate header もありません。各ステータスコードの条件は利用量とクォータを参照してください。

データ API のエラー

データ API（地震、気象、地図タイルなど）のエラー形式はエンドポイントによって違い、各ページのレスポンスと「注意事項」に書いてあります。共通する点：

多くの API は、無効なパラメータでも 400 を返さず、無視するか既定値に置き換えます。各ページの説明を正としてください。
404 と 5xx は HTML のエラーページであることがあり、JSON ではありません。そのまま JSON.parse すると失敗します。

OAuth2 のエラー

OAuth2 と公開情報 API のエラーは JSON で、形式は次に固定されています。

{ "error": "invalid_grant" }

これらのレスポンスは、成功時と同じく zstd で圧縮されています（Content-Encoding: zstd）。

`error`	HTTP	出現箇所	条件
`invalid_request`	400	token、`info/oauth-client`	フォームを解析できない。`client_id` がない
`invalid_client`	400	認可、`info/oauth-client`	`client_id` が存在しない
`invalid_client`	401	token	`client_id` が存在しない、または機密 client の `client_secret` が違う
`invalid_redirect_uri`	400	認可	`redirect_uri` がその client の登録一覧にない
`unsupported_grant_type`	400	token	`grant_type` が `authorization_code` ではない
`invalid_grant`	400	token	認可コードが存在しない、使用済み、期限切れ、または `client_id`、`redirect_uri`、PKCE が一致しない
`too_many_tokens`	403	token	ユーザーの token が 25 個に達している
`server_error`	500	token	サーバー内部エラー

redirect_uri が正当だと確認されたあと、認可エンドポイントのエラーは JSON を返さず、redirect_uri へ戻り、query に error を付けます。

`error`	条件
`unsupported_response_type`	`response_type` が `code` ではない
`invalid_request`	`code_challenge` がない、または `code_challenge_method` が `S256` ではない
`invalid_scope`	`scope` に存在しない権限名が含まれる
`access_denied`	ユーザーが認可を拒否した
`server_error`	サーバーが認可コードを作成できない

GET /api/v1/oauth2/userinfo が失敗したときは 401 で本文はありません。上の JSON ではありません。

配信のエラーと切断理由

次の文字列はサーバーが実際に送る原文です。完全一致かプレフィックス一致で処理してください。配信プロトコルの詳細はリアルタイム配信を参照してください。

接続が拒否された場合

接続の時点で失敗したリクエストは配信を開始せず、レスポンスはプレーンテキストです（末尾に改行があります）。

HTTP	本文	条件
400	`topics required, e.g. ?topics=…`	多重化の入口に `topics` がない
400	`unknown topic: <名称>`	topic 名が存在しない（大文字と小文字は一致させる）
401	`invalid token`	token を付けたが、無効または取り消し済み。公開 topic も拒否される
401	`unauthorized`	権限が必要な topic に token がない
403	`forbidden: token scope missing`	token にその topic の権限がない
403	`forbidden: not subscribed`	アカウントがそのリソースを購読していない
429	`quota exceeded`	そのリソースの今日のクォータを使い切った
503	`auth service unavailable`	認証サービスに一時的に接続できない
405	`method not allowed`	GET ではない

多重化の入口（/api/v1/trem/sse?topics=）で topic がすべて拒否されたとき、本文のうしろに : <topic> が付きます。例：forbidden: not subscribed: <topic>。1 つでも topic が通れば接続は成功し（200）、拒否された topic と理由は先頭の event: info の denied フィールドに並びます。理由の文字列は unauthorized、forbidden: token scope missing、forbidden: not subscribed、quota exceeded のいずれかで、topic 名は付きません。

接続中の中断

イベント	`data`	条件	推奨する対処
`unsubscribed`	`{"topic":"<topic>","reason":"quota exceeded"}`（JSON）	権限が必要な topic がクォータを超え、接続上には他の topic が残っている	その topic は送信を止め、他はそのまま
`close`	`quota exceeded`（プレーンテキスト）	接続上の最後の topic がクォータ超過で外された	すぐに再接続せず、クォータが戻るまで待つ
`close`	`token revoked`（プレーンテキスト）	アカウントのいずれかの token が取り消され、約 5 秒後にそのアカウントの認証済み接続がすべて閉じられる	まだ有効な token で接続し直す。取り消された token では `invalid token` になる

サーバーは、書き込みがタイムアウトしたとき（約 30 秒書き出せないとき）は close イベントを送らず、そのまま切断します。クライアントは「close のない切断」をネットワークの問題として扱い、retry: 3000（3 秒）に従って再接続してください。