REST API のエラー


この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です

このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。

REST API は、失敗したときに RFC 9457 の application/problem+json の形でエラーを返します。このページでは、形の読み方と、すべての code の原因と対処を説明します。

エラーの形

{
  "type": "https://developer.a-blogcms.jp/rest-api/problems/validation-failed",
  "title": "入力内容にエラーがあります。",
  "status": 422,
  "detail": "2 件の項目を修正してください。",
  "instance": "/rest-api/acms/v1/entries/",
  "code": "validation_failed",
  "errors": [
    { "pointer": "#/fields/event_date", "code": "required", "detail": "このカスタムフィールドは入力が必要です。" },
    { "pointer": "#/tags", "code": "reserved", "detail": "予約語は使えません。" }
  ]
}

キー

内容

type

エラーの種類の URI(https://developer.a-blogcms.jp/rest-api/problems/ に code の _ を - にした名前)

title

種類ごとに決まった文言(翻訳されます)

status

HTTP のステータスコード

detail

このリクエストでの説明(無いこともあります。翻訳されます)

instance

リクエストのパス

code

エラーの種類を表す、変えない約束の値。プログラムでは status と code で分岐してください

errors

問題のある箇所の一覧(あるときだけ)。本文の誤りは pointer(#/title のような JSON Pointer)、クエリの誤りは parameter(クエリの名前)で示します。errors[].code は、required・maxlength・max_items・in・regex・email・reserved・invalid・min_rows など、項目ごとの誤りの種類です

  • title と detail は、トークンのユーザーの言語(無ければ Accept-Language、それも無ければサイトの既定)で返ります。分岐には使わないでください。

  • 1 回のリクエストの誤りは、できるだけまとめて errors に入ります。すべて直してから送り直してください。

  • 本番環境(デバッグモードでない)では、500 のエラーの中身を出しません(internal_error)。原因は監査ログとサーバーのエラーログで確かめます。

code の一覧(400〜404)

ステータス

code

原因

対処

400

malformed_json

本文を JSON として解析できない

JSON の構文(カンマ・引用符・エスケープ)を確かめる。シェルのクォートで崩れやすいので、ファイルに書いて --data-binary @file.json で送る

400

invalid_parameter

クエリの値・名前、If-Match の形式が正しくない(errors[].parameter に名前)。例: dry_run=true、indexing=yes、fields に無い項目名、If-Match: *

detail と errors のとおりに直す

400

invalid_idempotency_key

Idempotency-Key が 1〜255 文字の印字可能な ASCII でない(日本語・空など)

UUID などの ASCII の値にする

401

missing_token

トークンが届いていない

Authorization: Bearer acms_... を付ける。付けているなら Web サーバーがヘッダーを落としていないか(.htaccess)を確かめる

401

invalid_token

トークンが正しくない・失効している

値のコピー漏れを確かめる。失効していれば発行し直す

401

token_expired

トークンの有効期限が切れている

新しいトークンを発行する

401

user_disabled

トークンの持ち主のユーザーが無効になっている

ユーザーの状態を管理画面で確かめる

403

forbidden

管理画面の権限が足りない(投稿者がほかの人のエントリーを更新する、編集者がモジュール ID を作るなど)

ユーザーの権限・ロールを見直すか、権限のあるユーザーのトークンを使う

403

insufficient_scope

トークンのスコープが足りない。WWW-Authenticate の scope に要るスコープ

要るスコープを付けたトークンを発行し直す

403

https_required

HTTP で接続した

HTTPS の URL で呼ぶ

403

ip_restricted

接続元の IP アドレスが「接続元 IP アドレス」の範囲外

設定に接続元を足すか、許可された場所から呼ぶ

403

blog_not_allowed

トークンの持ち主が操作できないブログの URL で呼んだ

所属ブログか、その子孫のブログ(「子ブログにも権限を与える」が有効な場合)の URL で呼ぶ

403

api_access_not_allowed

このユーザーに API・MCP の利用が許可されていない

管理者に「API・MCP を使える権限」かロールの「API・MCP の接続」を確かめてもらう

404

not_found

リソースが無い。閲覧の権限が無いもの、URL のブログの範囲の外のもの、ゴミ箱のエントリー(?status=trash なし)を含む

ID・ブログの URL・status を確かめる

404

route_not_found

エンドポイントが無い(パスの誤り)

パスと名前空間を確かめる(エンドポイント一覧)。トークンが無いときは、ルートの有無を知らせず 401 になります

code の一覧(405〜500)

ステータス

code

原因

対処

405

method_not_allowed

そのパスで使えないメソッド(OPTIONS を含む)。Allow ヘッダーに使えるメソッド

Allow のメソッドで呼ぶ

409

approval_workflow_required

承認フローのため、この方法では変更できない

承認フローの操作(POST /entries/{id}/approvals)で進める

409

entry_locked

ほかのユーザーが編集ロックしている

ロックが解除されるのを待つか、ロックした人に解除を頼む

409

conflict

今の状態では実行できない(ゴミ箱にないエントリーを戻す、同じ処理のジョブが実行中、Idempotency-Key の最初のリクエストが処理中、使われているコンフィグセット・ロールの削除、最後の管理者の削除など。detail に理由)

detail の理由を解消してから送り直す

410

gone

廃止日(Sunset)を過ぎたエンドポイント

告知された移行先を使う

412

precondition_failed

If-Match が現在の ETag と違う(取得した後にほかの変更が入った)。必須のエンドポイントで If-Match が無い場合も

取得し直し、変更を反映してから、新しい ETag で送り直す。412 の応答の ETag ヘッダーに現在の値が入ります

413

payload_too_large

本文が上限(既定 2 MiB)を超えた

本文を分ける。上限は rest_api_max_body_size

415

unsupported_media_type

Content-Type が対応していない

JSON は application/json、ファイルは multipart/form-data で送る

422

validation_failed

入力の誤り(必須・文字数・選択肢・カスタムフィールドの定義・エントリー項目設定・予約語など。errors に箇所)

errors[].pointer の項目を直す

422

unknown_field

本文に未知の項目がある(errors[].code が unknown_field)

項目名の綴りを確かめる。表現に無い項目は送れません

422

read_only_field

読み取り専用の項目(id・url・links・sort など)や、ロールの設定で変えられないカスタムフィールドを送った

その項目を本文から除く

422

unsupported_unit_type

API から書き込めないユニット(image・file・eximage・プラグインの独自ユニット)

画像・ファイルはメディアを登録して media ユニットで参照する(エントリーの本文とカスタムフィールドを送る)

422

unknown_config_key

REST API で扱えない設定キーを送った

GET /configs の一覧にあるキーだけを送る

422

idempotency_key_reused

同じ Idempotency-Key を別の内容(メソッド・ブログ・パス・本文のどれかが違う)で使った

内容ごとに新しいキーを使う

429

rate_limited

リクエストが多すぎる(リクエスト上限・削除などの操作の上限・認証の失敗の上限・Webhook のテスト送信の上限)

Retry-After の秒数だけ待ってから送り直す

500

internal_error

サーバーのエラー

監査ログとサーバーのエラーログを確かめる。続く場合はサイトの管理者に連絡する

プラグインが追加したエンドポイントも、同じ形・同じ code で失敗を返します。

実際の応答の例

未知の項目と読み取り専用の項目を同時に送った場合の例です。種類の違う誤りがあるときは、全体の code は unknown_config_key・unknown_field・read_only_field・unsupported_unit_type・validation_failed の順で先のものになり、項目ごとの種類は errors[].code で分かります。未知の項目などを直すと、次の送信で入力の検証の誤りが返ることがあります。

curl -s -X PATCH "${ACMS_API}/entries/240/?dry_run=1" -H "Authorization: Bearer ${ACMS_API_TOKEN}" \
  -H "Content-Type: application/json" -d '{"titel":"x","id":5}'
{
  "type": "https://developer.a-blogcms.jp/rest-api/problems/unknown-field",
  "title": "未知の項目があります。",
  "status": 422,
  "detail": "2 件の項目を修正してください。",
  "instance": "/rest-api/acms/v1/entries/240/",
  "code": "unknown_field",
  "errors": [
    { "pointer": "#/titel", "code": "unknown_field", "detail": "この項目はありません。" },
    { "pointer": "#/id", "code": "read_only_field", "detail": "この項目は変更できません。" }
  ]
}

クエリの誤りは parameter で示します。

{
  "type": "https://developer.a-blogcms.jp/rest-api/problems/invalid-parameter",
  "title": "パラメータが正しくありません。",
  "status": 400,
  "instance": "/rest-api/acms/v1/entries/",
  "code": "invalid_parameter",
  "errors": [
    { "parameter": "fields", "code": "invalid", "detail": "fields に未知の項目 \"foo\" があります。" }
  ]
}

使えないメソッドには Allow が付きます。

HTTP/2 405
allow: GET, HEAD, POST
content-type: application/problem+json; charset=utf-8

{"type":"https://developer.a-blogcms.jp/rest-api/problems/method-not-allowed","title":"このメソッドは使えません。","status":405,"instance":"/rest-api/acms/v1/entries/","code":"method_not_allowed"}

429 には、残りの回数を表すヘッダーと Retry-After が付きます。

HTTP/2 429
content-type: application/problem+json; charset=utf-8
ratelimit-policy: "default";q=300;w=60
ratelimit: "default";r=0;t=23
retry-after: 23

{"type":"https://developer.a-blogcms.jp/rest-api/problems/rate-limited","title":"リクエストが多すぎます。しばらく待ってから再試行してください。","status":429,"instance":"/rest-api/acms/v1/entries/","code":"rate_limited"}

エラーを監査ログで確かめる

権限・スコープで拒否したリクエストは、監査ログに「REST API の認可に失敗しました」(NOTICE)として残ります。経路「REST API」の記録に、使ったトークンの名前・接続元・メソッド・パス・ルート名・HTTP のステータスが入ります。

よくある質問・つまずき

title の文言で分岐してよいですか

使わないでください。文言は翻訳やバージョンで変わります。status と code(項目ごとは errors[].code)は変えない約束の値です。

type の URL を開くと見つかりません

type はエラーの種類を表す識別子です。説明はこのページの表を参照してください。

同じ 404 でも、存在しないのか見えないのか分かりません

意図して区別していません。閲覧の権限が無いリソースの存在を知らせないためです。権限のあるユーザーのトークンで確かめるか、管理画面で存在を確かめてください。