メインコンテンツへスキップ
APIが拒否したリクエストは、HTTPのエラーステータスと次のエンベロープを返します。
code は安定しているので、これで分岐してください。message は人間向けで、変わることがあります。details は補足があるときに含まれます。検証エラーでは通常 { field, message } の配列、それ以外では { "id": "..." } や { "retryAfterSec": 5, "retryable": true } のようなオブジェクトです。 受け付けられた後に失敗したタスクはHTTPエラーを生みません。代わりにタスクの失敗コードを報告します。

リクエストエラーコード

ステータスより error.code を優先してください。VALIDATION_ERROR は 400 と 422 の両方で現れます。429 は自分の上限に達したこと、503 はサーバーの処理能力が一時的に足りないことを示します。

Retry-After

POST /v1/async/task、POST /v1/async/task/batch、POST /v1/async/task/grid では、すべての 429 と 503 に秒単位の Retry-After ヘッダーが付きます。これらのコードの多くは details.retryAfterSec と details.retryable: true も持ちます。エッジのリクエスト上限による 429 にはどちらも付きません。クレジットと上限を参照してください。

ペイロードサイズの上限

地域による拒否

REGION_UNSUPPORTED はタスクをキューに入れる前に判定されるため、タスクの失敗を待たずにすぐ分かります。
どのエンジンがどの国を提供するかは地域と位置に記載しています。

バッチとグリッドの項目ごとのエラー

POST /v1/async/task/batch では、正しい形式のリクエストは項目が失敗しても 200 を返します。ステータスはリクエストを、results[].success は各タスクを表し、失敗した項目はリクエストエラーと同じ { code, message, details, timestamp } オブジェクトを持ちます。
429のコード、QUEUE_BACKPRESSURE、SERVER_OVERLOADED で失敗した項目は、待ち時間を details.retryAfterSec に持ちます。リクエスト自体が 400、413、429、503 で失敗するのは、バッチ全体が拒否された場合だけです。 POST /v1/async/task/grid は、拒否された地点を同じ方法で points[] に報告します。POST /v1/batches は、不正な項目が1つでもあれば 400 でバッチ全体を拒否し、受け付け処理で拒否された項目(INSUFFICIENT_CREDITS など)を REJECTED として保存します。idempotencyKey がバッチより前に作成されたタスクと一致した項目は、そのタスクが保持されなくなると TASK_NOT_RETAINED 付きの FAILED として返ります。バッチとグリッドを参照してください。

タスクの失敗コード

キューに入った後に失敗したタスクは FAILED で終わります。ポーリングは、リクエストエラーのオブジェクトではなく、トップレベルの error 文字列を返します。
Webhookは同じ文字列を response.error に入れます。文字列はコードで始まるため、それで分岐してください。

タスク失敗コードの変更履歴