エラーの一覧

API がうまくいかなかったときに返るエラーの形と、状態ごとの原因と直し方の一覧です。Content API とメディアの API は同じ形、Admin API は別の形で返ります。

Content API

Content API（/api/v1/content/…）とメディアの API（/api/v1/media/…）は、エラーを次の形で返します。

{
  "error": {
    "code": "bad_request",
    "message": "title: is required",
    "details": {
      "issues": [{ "path": "title", "message": "is required" }]
    }
  }
}

項目	中身
code	状態ごとに決まった名前。プログラムで分けるときは、これを使う
message	人が読むための英語の文。変わることがあるので、プログラムで比べない
details.issues	入力が決まりに合わないときだけ。path（どこか）と message（なぜか）の配列
details.limit	limit_reached のときだけ。上限の名前と値

状態	code	原因	直し方
400	bad_request	パラメーター、where、本文が決まりに合わない。知らないパラメーター。スキーマに合わない値。応答が 5 MB を超える。シングルに POST した	message と details.issues に、どこが違うかが出ます。応答が大きすぎるときは、limit や select で減らします
401	unauthorized	API キーがない、違う、または失効している。パスのスペースが、キーのスペースと違う	Authorization: Bearer のあとに、hako_ で始まるキーをそのまま入れているか確かめます。失効していれば、［API キー］の画面で確かめます
403	forbidden	キーに、その操作の権限がない（this API key cannot create entries など）。権限のないキーで preview=true を付けた	［API キー］の画面で、キーの権限を確かめます。［個別に設定］のコンテンツタイプは、個別の権限だけで決まります
404	not_found	コンテンツタイプかエントリーがない。公開していない。/api/v1 の知らないパス	URL のコンテンツタイプ ID が［エンドポイント］と同じか、エントリーが［公開中］か確かめます
405	method_not_allowed	そのパスで使えないメソッド	Content API のリファレンス で、操作のメソッドを確かめます
409	conflict	ID や重複を許さない値が、ほかと重なった。sys.version が今の版と違う。今の状態ではできない操作（捨てる下書きがない、公開していないものの公開をやめる、ほかから参照されているものを削除するなど）	版が違うときは、エントリーを読み直してから書き直します
409	limit_reached	使える量の上限に達した（エントリーの数、メディアの大きさの合計）	details.limit に、どの上限かが出ます。要らないものを消すか、使える量の上限 を見てください
413	payload_too_large	アップロードしたファイルが大きすぎる	ファイルを小さくします
414	uri_too_long	URL が 8 KB を超える	where や select を短くします
415	unsupported_media_type	メディアのアップロードが multipart/form-data でない	file の部分にファイルを入れた multipart/form-data で送ります
422	unprocessable_entity	本文の形が違う（知らないキーなど）	message に出たキーを確かめます
429	too_many_requests	送りすぎ	少し待ってから送り直します
500	internal	Hako CMS の中のエラー	時間をおいても続くときは、送った日時と URL を添えて問い合わせてください

limit_reached のときは、次のように返ります。

{
  "error": {
    "code": "limit_reached",
    "message": "this space has reached its limit of 100 entries; ask the server operator to raise it",
    "details": { "limit": { "name": "space.entries", "max": 100 } }
  }
}

where の書き方の誤りは、400 で、何文字目が違うかが message に出ます。例は 絞り込む、並べる、ページに分ける にあります。リッチテキストの誤りは リッチテキストの形 にあります。

Admin API

Admin API（/admin/api/…）は、エラーを次の形で返します。

{ "message": "slug already exists" }

入力が決まりに合わないときは、issues も付きます。message は、issues を ; でつないだものです。

{
  "message": "fields.id: fieldId is reserved; fields.n: min must not exceed max",
  "issues": [
    { "path": "fields.id", "message": "fieldId is reserved" },
    { "path": "fields.n", "message": "min must not exceed max" }
  ]
}

操作によっては、ほかの項目も付きます（スキーマの更新で合わないエントリーの数 violationCount など）。

状態	原因	直し方
400	入力の値が決まりに合わない。JSON の書き方の誤り	message と issues に、どこが違うかが出ます
401	ログインしていない（login required）。アクセストークンが違う、期限を過ぎた、取り消した（invalid or expired access token）	Authorization: Bearer のあとに、hako_pat_ で始まるトークンを入れているか確かめます。期限を過ぎていれば、新しく作ります
403	権限が足りない（you do not have permission to do this）。［読み取りだけ］のトークンで書き込んだ（this access token can only read）。トークンではできない操作（access tokens cannot do this; sign in to the admin UI）。別のサイトからの書き込み（cross-origin request rejected）	ロールの権限か、トークンの［できること］を確かめます。トークンを作る操作は、管理画面にログインして行います
404	対象がない。メンバーでないスペース（あることを知らせないため 404 にします）	パスのスラッグや ID と、スペースのメンバーかを確かめます
409	名前や ID が重なった。ほかの人が先に変えて版が古い（schema was changed by someone else など）。参照されていて消せない。今の状態ではできない操作。確かめが要る（confirm を付けて送り直す）。使える量の上限に達した	message を読み、読み直してから送り直します
415	Content-Type: application/json がない	本文が JSON のときは、ヘッダーを付けます
422	JSON の書き方は正しいが、必須のキーがない、型が違う、知らないキーがある	message に出たキーを確かめます
429	送りすぎ（ログインの失敗が多い、など）	Retry-After ヘッダーの秒数だけ待ってから送り直します
500	Hako CMS の中のエラー	時間をおいても続くときは、送った日時と URL を添えて問い合わせてください

使える量の上限に達したときは、409 で、limit に上限の名前と値が入ります。

{
  "message": "this space has reached its limit of 100 entries; ask the server operator to raise it",
  "limit": { "name": "space.entries", "max": 100 }
}

limit.name	数えるもの	止まる操作
spaces	スペース	スペースの作成、取り込み
users	削除していないユーザー	ユーザーの作成、アカウントのない人の招待と受け入れ
media	メディアの大きさの合計（環境全体）	メディアのアップロード、取り込み
space.content_types	コンテンツタイプ	コンテンツタイプの作成、スキーマの反映、取り込み
space.entries	エントリー（すべてのコンテンツタイプの合計）	エントリーの作成、取り込み
space.members	メンバーと、受け入れられていない招待	招待
space.api_keys	失効していない API キー	API キーの発行、失効したキーを戻す
space.webhooks	Webhook	Webhook の作成、取り込み
space.media	メディアの大きさの合計（スペース）	メディアのアップロード、取り込み

上限を超えても、今あるものは消えません。増やす操作だけが止まります。今の使用量は、Admin API の 使用量 で取れます。

画像の配信と変換

画像の URL に変換のパラメーターを付けたときは、次のエラーが返ります。形は Admin API と同じ { "message": … } です。

状態	message の例	原因	直し方
400	w: must be an integer between 1 and 8192	パラメーターの値が範囲の外、または正しくない	画像を変換して出す で、値の範囲を確かめます
400	fm: png is only available for PNG images	PNG でない画像に fm=png を付けた	ほかの形式（webp など）にします
400	image is too large to transform	画像の画素数が多すぎて変換できない	小さい画像を上げ直します。変換しない元の画像は配信できます

JPEG、PNG、WebP、GIF でないファイル（SVG など）に変換のパラメーターを付けても、エラーにはならず、元のファイルが返ります。

関連

• Content API のリファレンス
• Admin API のリファレンス
• エントリーを取り出す