Skip to content

エラー ​

エラーの形式 ​

失敗した場合は常に同じ形式が返ります。

json
{
  "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_INVALID400IP アドレス、範囲、ISO の国コードではない。ホスト部が 0 でない範囲(メッセージに正しい範囲が出ます)。未知の kind や applies_to
NETWORK_RULE_TOO_WIDE400IPv4 で /8、IPv6 で /16 より広い範囲
NETWORK_RULE_LIMIT409ネットワークルールの制限を超えた
NETWORK_SELF_LOCKOUT409新しい許可リストでは 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 がアーカイブ直下ではなくフォルダの中に入っているバンドルです。

あわせて読む ​