エラー
エラーの形式
失敗した場合は常に同じ形式が返ります。
{
"error": {
"code": "forbidden",
"message": "workspace does not belong to organization"
}
}code は安定しており、分岐条件に使えます。message は人間向けで、変更される可能性があります。
ステータスコード
| ステータス | 意味 | よくある原因 |
|---|---|---|
| 401 | 認証されていない | トークンがない、期限切れ、または別の audience 向けのトークン |
| 403 | 認証済みだが許可されていない | スコープの不足、または別の組織に属するワークスペース |
| 404 | このワークスペースに存在しない | 不明な id、slug、ドメイン。使用していないワークスペースに存在する場合も含む |
| 409 | 現在の状態と競合する | slug がすでに使用中、未検証のドメインを割り当てようとした、終わったワークフローの実行にシグナルを送った(run_finished)、送信されたファイルのダウンロードリンクをスキャンが clean になる前に使った(not_ready) |
| 422 | 検証に失敗した | 確認用フィールドが一致しない、許可された値の範囲外、distribution の タイプ に合わないゴールやファネル |
| 413 | 大きすぎる | キューへの送信で、メッセージ本文または合計サイズが上限を超えた(too_large) |
| 429 | レート制限 | ドメイン作成の繰り返し、エンドポイントが分あたりの上限を超えた場合、キューへの送信が速すぎる(rate_limited)か満杯のキューに送った(queue_full)場合、実行中の実行数の上限を超えてワークフローを開始した(limit_reached)場合、またはエージェントやトークンがフォームの送信内容の 1 日の読み取り上限を超えた場合。制限 を参照 |
理解しておきたいもの
有効に見えるトークンで 401
トークンは audience ごとに発行されます。MCP サーバー向けのトークンは https://api.edge.deca-dev.com 向けのトークンではありません。同じ資格情報でエージェント経由では動くのに HTTP では動かない場合、まず audience を確認してください。
403 ACCESS_DOWNGRADE
distribution を公開にする、require_mfa を外す、サインイン方式を減らす、には access.write が必要です。メッセージは対象のフィールド名を含みます。distribution は変わりません。
NETWORK_* コード
ネットワークルールの変更は、すべて適用されるか、まったく適用されないかのどちらかです。
| コード | ステータス | 意味 |
|---|---|---|
NETWORK_RULE_INVALID | 400 | IP アドレス、範囲、ISO の国コードではない。ホスト部が 0 でない範囲(メッセージに正しい範囲が出ます)。未知の kind や applies_to |
NETWORK_RULE_TOO_WIDE | 400 | IPv4 で /8、IPv6 で /16 より広い範囲 |
NETWORK_RULE_LIMIT | 409 | ネットワークルールの制限を超えた |
NETWORK_SELF_LOCKOUT | 409 | 新しい許可リストでは caller_ip が拒否される。そのアドレスも追加するか、confirm を付けてやり直す |
他の呼び出しは通るのに 403
原因はふたつあり、メッセージで区別できます。
- スコープの不足。 メッセージに必要なスコープ名が含まれます。権限スコープ を参照してください。
- 組織外のワークスペース。 Edge はトークンが組織をまたぐことを許しません。パスの
{org_id}を使った場合も同様で、この値はトークンの組織と一致する必要があります。
コンソールでは見えるのに 404
distribution と関連リソースはワークスペース単位です。複数のワークスペースを持っていて、リクエストが default ワークスペースに解決された場合、別のワークスペースにある distribution はそのリクエストから見て本当に存在しません。クエリパラメータまたは JSON フィールドとして workspace_id を渡してください。GET /v1/logs/stream は明示的な指定が必須です。
ドメイン割り当てで 409
ドメインは割り当て前に検証が必要です。DNS が未反映のとき、検証は呼び出し側から見ると静かに失敗します。TXT レコードがまだ見えていないだけです。待ってから再検証し、そのあと割り当ててください。
削除で 422
distribution とドメインの削除には、対象の識別子をリクエストボディで繰り返す必要があります。distribution は slug、ドメインは confirm_fqdn です。値が一致しない場合は削除されず 422 が返ります。
ファイルの読み取りで 422
読めるのはスキャンが clean で終わったファイルだけです。scanning、rejected、scan_failed のファイルは拒否され、メッセージにその状態が示されます。content は 10 MiB までの画像と PDF だけ、text は抽出テキストがあるファイルだけで使えます。それ以外は link を要求してください。
訪問者向けのレーン
/_upload と /_submit は API クライアントではなく訪問者のブラウザーに応答し、{"error": "invalid_upload", "field": "resume", "reason": "type"} のような平らなボディを使います。コードの一覧は フォームのアップロード にあります。
deployment の失敗は HTTP エラーではありません
処理できなかった deployment があっても、それを作成したリクエストが失敗するわけではありません。リクエストは成功し、その後で deployment の status が failed になります。
つまり commit が 200 を返したことは、処理が受け付けられたという意味であって、成功したという意味ではありません。GET /v1/deployments/{id} を status が ready か failed になるまでポーリングしてください。
最もよくある原因は、gzip 圧縮された tar ではないバンドル、または index.html がアーカイブ直下ではなくフォルダの中に入っているバンドルです。