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": "予約語は使えません。" }
]
}キー | 内容 |
|---|---|
| エラーの種類の URI( |
| 種類ごとに決まった文言(翻訳されます) |
| HTTP のステータスコード |
| このリクエストでの説明(無いこともあります。翻訳されます) |
| リクエストのパス |
| エラーの種類を表す、変えない約束の値。プログラムでは |
| 問題のある箇所の一覧(あるときだけ)。本文の誤りは |
titleとdetailは、トークンのユーザーの言語(無ければAccept-Language、それも無ければサイトの既定)で返ります。分岐には使わないでください。1 回のリクエストの誤りは、できるだけまとめて
errorsに入ります。すべて直してから送り直してください。本番環境(デバッグモードでない)では、500 のエラーの中身を出しません(
internal_error)。原因は監査ログとサーバーのエラーログで確かめます。
code の一覧(400〜404)
ステータス |
| 原因 | 対処 |
|---|---|---|---|
400 |
| 本文を JSON として解析できない | JSON の構文(カンマ・引用符・エスケープ)を確かめる。シェルのクォートで崩れやすいので、ファイルに書いて |
400 |
| クエリの値・名前、 |
|
400 |
|
| UUID などの ASCII の値にする |
401 |
| トークンが届いていない |
|
401 |
| トークンが正しくない・失効している | 値のコピー漏れを確かめる。失効していれば発行し直す |
401 |
| トークンの有効期限が切れている | 新しいトークンを発行する |
401 |
| トークンの持ち主のユーザーが無効になっている | ユーザーの状態を管理画面で確かめる |
403 |
| 管理画面の権限が足りない(投稿者がほかの人のエントリーを更新する、編集者がモジュール ID を作るなど) | ユーザーの権限・ロールを見直すか、権限のあるユーザーのトークンを使う |
403 |
| トークンのスコープが足りない。 | 要るスコープを付けたトークンを発行し直す |
403 |
| HTTP で接続した | HTTPS の URL で呼ぶ |
403 |
| 接続元の IP アドレスが「接続元 IP アドレス」の範囲外 | 設定に接続元を足すか、許可された場所から呼ぶ |
403 |
| トークンの持ち主が操作できないブログの URL で呼んだ | 所属ブログか、その子孫のブログ(「子ブログにも権限を与える」が有効な場合)の URL で呼ぶ |
403 |
| このユーザーに API・MCP の利用が許可されていない | 管理者に「API・MCP を使える権限」かロールの「API・MCP の接続」を確かめてもらう |
404 |
| リソースが無い。閲覧の権限が無いもの、URL のブログの範囲の外のもの、ゴミ箱のエントリー( | ID・ブログの URL・ |
404 |
| エンドポイントが無い(パスの誤り) | パスと名前空間を確かめる(エンドポイント一覧)。トークンが無いときは、ルートの有無を知らせず 401 になります |
code の一覧(405〜500)
ステータス |
| 原因 | 対処 |
|---|---|---|---|
405 |
| そのパスで使えないメソッド( |
|
409 |
| 承認フローのため、この方法では変更できない | 承認フローの操作( |
409 |
| ほかのユーザーが編集ロックしている | ロックが解除されるのを待つか、ロックした人に解除を頼む |
409 |
| 今の状態では実行できない(ゴミ箱にないエントリーを戻す、同じ処理のジョブが実行中、Idempotency-Key の最初のリクエストが処理中、使われているコンフィグセット・ロールの削除、最後の管理者の削除など。 |
|
410 |
| 廃止日( | 告知された移行先を使う |
412 |
|
| 取得し直し、変更を反映してから、新しい |
413 |
| 本文が上限(既定 2 MiB)を超えた | 本文を分ける。上限は |
415 |
|
| JSON は |
422 |
| 入力の誤り(必須・文字数・選択肢・カスタムフィールドの定義・エントリー項目設定・予約語など。 |
|
422 |
| 本文に未知の項目がある( | 項目名の綴りを確かめる。表現に無い項目は送れません |
422 |
| 読み取り専用の項目( | その項目を本文から除く |
422 |
| API から書き込めないユニット( | 画像・ファイルはメディアを登録して |
422 |
| REST API で扱えない設定キーを送った |
|
422 |
| 同じ | 内容ごとに新しいキーを使う |
429 |
| リクエストが多すぎる(リクエスト上限・削除などの操作の上限・認証の失敗の上限・Webhook のテスト送信の上限) |
|
500 |
| サーバーのエラー | 監査ログとサーバーのエラーログを確かめる。続く場合はサイトの管理者に連絡する |
プラグインが追加したエンドポイントも、同じ形・同じ 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 でも、存在しないのか見えないのか分かりません
意図して区別していません。閲覧の権限が無いリソースの存在を知らせないためです。権限のあるユーザーのトークンで確かめるか、管理画面で存在を確かめてください。