Java
エラーと再試行
拒否の種類ごとに 1 つの例外クラス、そして二重に送信しない再試行。
エラーの処理
try { client.templates().send("order-shipped", Body.of( "from", "[email protected]", "to", "[email protected]", "props", Body.of("orderId", "AC-4192") ));} catch (ValidationException error) { System.err.println(error.param() + " " + error.getMessage());} catch (RateLimitException error) { System.err.println("Wait " + error.retryAfterSeconds() + " seconds");} catch (ApiException error) { System.err.println(error.status() + " " + error.code() + " " + error.requestId());} catch (NetworkException error) { System.err.println(error.isTimeout() ? "Timed out" : "No response");}API に拒否されると、ApiException またはその種類に対応するサブクラスが、API が伝えた内容とともにスローされます。クライアントがスローする例外はすべて非チェック例外の OpenEmailException なので、1 つの catch ですべてを捕捉できます。
| メソッド | 内容 |
|---|---|
| status() | HTTP ステータス。応答が届かなかった場合は 0 です。 |
| type(), code() | API のエラー型とコード。たとえば validation_error と invalid_parameter です。 |
| param() | 原因となったフィールド。ある場合のみです。 |
| requestId() | サポートに連絡するときに伝える id です。 |
| docUrl() | そのコードを説明するドキュメントのページです。 |
| retryAfterSeconds() | API が待つよう求めた時間。 |
| fields() | 登録フォームが拒否したフィールド。それぞれに key と error があります。 |
| body() | デコードされたレスポンスボディです。 |
失敗の種類
| 例外 | スローされるとき |
|---|---|
| AuthenticationException | キーまたはトークンが拒否されました。401 です。 |
| PermissionException | この資格情報ではその操作が許可されていません。403 です。 |
| NotFoundException | その id を持つものがありません。404 です。 |
| ConflictException | 変更が現在の状態と競合しています。409 です。 |
| ValidationException | フィールドが拒否されました。422 です。 |
| RateLimitException | リクエストが多すぎるか、割り当てを使い切りました。429 です。 |
| InvalidRequestException | リクエストに対するそれ以外の拒否です。 |
| ApiException | API が失敗しました。ステータスは 500 以上です。 |
| NetworkException | 応答が届きませんでした。 |
| IllegalArgumentException | 呼び出しそのものに誤りがあり、何も送信されませんでした。 |
| WebhookSignatureException | Webhook の配信が検証に失敗しました。 |
ApiException は自身についての問いにも答えます。isValidation()、isNotFound()、isRateLimited()、isServerError()、isRetryable() に加え、呼び出しに必要なスコープが資格情報にないときの isScopeMissing()、アクセストークンが先にコードを検証する必要があるときの isStepUpRequired() があります。NetworkException.isTimeout() は期限が過ぎたことを示します。
再試行されるもの
- 読み取り、送信、繰り返しても安全なすべての書き込みは、最大
maxRetries回まで再試行されます。それ以外の書き込みは 1 回だけ送信されます。 - ステータス 408、500、502、503、504 は、0.5 秒から始まり 8 秒まで倍増する待ち時間をはさんで再試行されます。
- 429 は、1 分以内の
Retry-Afterが付いている場合にだけ再試行され、クライアントはその時間だけ待ちます。 - 失敗した接続やタイムアウトした接続も同じように再試行されます。
再試行される送信は毎回同じ冪等性キーを持つため、API は 2 通目を送らずに最初のメッセージを再生します。