エラーとステータスコード

エラーは常に同じ形の JSON で返り、常に安定した機械可読のコードを伴います。メッセージではなくコードで分岐してください。

形

あらゆる失敗は、人間が読める error と安定した code を持つオブジェクトを返します。メッセージは人間向けに書かれており言い換えられることがありますが、コードは約束であり、断りなく変わることはありません。

{
  "error": "That file is larger than the 200 MB limit on your plan.",
  "code": "VALIDATION_FAILED"
}

コード	HTTP	意味
NOT_AUTHENTICATED	401	ベアラートークンが無いか、形式が不正です
FORBIDDEN	403	キーは有効ですが、この操作は許可されていません
NOT_ENTITLED	402	アカウントのプランに API アクセスが含まれていません
VALIDATION_FAILED	400 / 413	不正なリクエスト、非対応の変換、またはファイルが大きすぎます
NOT_FOUND	404	そのジョブは存在しないか、別のアカウントのものです
RATE_LIMITED	429	1 時間あたりの上限に達しました。待って再試行してください。
INTERNAL	500	当方側で問題が発生しました。再試行して構いません。

429 と 500 は間隔を空けて再試行する価値があります。ループで回すのではなく待ち時間を伸ばしてください。再試行も他のリクエストと同様に 1 時間あたりの上限に数えられます。

それ以外はそのリクエストについては確定です。400、402、404 を再試行しても同じ答えが返るだけで、それを確かめるために上限を消費します。

JSON の本文を伴わない 502 や 503 はアプリケーションからのものではありません。前段のプロキシによるもので、その場合は常に再試行する価値があります。