スタート

エラー

すべてのエラーに 1 つの形。分岐のためのコードと、ログのための詳細。

形

JsonError

{
  "errors": [
    {
      "code": "string, stable, branch on it",
      "detail": "string, English, for logs, never shown to users",
      "source": {
        "pointer": "the refused path parameter, when there is one"
      }
    }
  ]
}

code で分岐してください。安定した機械可読の値で、新しいコードは追加されるだけです。detail はログ行のための英語の文章で、ユーザーには表示しないでください。source.pointer は拒否されたパスパラメータのときに現れ、そのパラメータを指します。

/v1 が返すすべてのコード

ステータス	コード	いつ	どうするか
401	`unauthorized`	リクエストにキーがない。	ベアラーを送る。
401	`api_key_invalid`	immit が発行したキーではない。	貼り付けを確認する。
401	`api_key_revoked`	コンソールで無効化された。	代わりのキーを使う。
401	`api_key_suspended`	immit の担当者が停止した。	メールを読み、返信する。
404	`not_found`	見出し語に一致するエントリー、表記、大文字小文字の変種がない。	代わりに検索する。ユーザーが見たのは検索が解決する活用形かもしれません。
429	`rate_limited`	1 分のバーストを使い切った。	`retry-after` 秒待つ。
429	`quota_exceeded`	1 日のクォータを使い切った。	UTC の 0 時を待つか、ティアを上げる。
422	`invalid_param`	パラメータが仕様と違う。fra という lang、数値でない limit など。25 を超える limit は拒否されず上限に丸められます。	`detail` を読み、パラメータを指す `source.pointer` があればそれも読む。
5xx	さまざま	immit 側の問題。	バックオフしてリトライする。一時的でないならステータスページが伝えます。

404 · application/json

{
  "errors": [
    {
      "code": "not_found",
      "detail": "Not Found"
    }
  ]
}

422 · application/json

{
  "errors": [
    {
      "code": "invalid_param",
      "source": {
        "pointer": "/lang"
      },
      "detail": "Invalid value for enum"
    }
  ]
}

未知のコード

知らないコードに出会ったクライアントは、そのステータスの汎用的な文言にフォールバックしてください。コードはフィールドと同じく、バージョンを上げずに /v1 に追加されます。