C#
エラーと再試行
すべての拒否に 1 つの例外型、種類ごとに 1 つのプロパティ、そして二重送信を起こさない再試行。
エラーの処理
try{ await client.Emails.SendAsync(new Body { ["from"] = "[email protected]", ["to"] = "[email protected]", ["subject"] = "Your September invoice", ["text"] = "Invoice attached.", });}catch (OpenEmailApiException error) when (error.IsValidation){ Console.Error.WriteLine($"{error.Code} {error.Param} {error.Message}");}catch (OpenEmailApiException error) when (error.IsRateLimited){ Console.Error.WriteLine($"try again in {error.RetryAfterSeconds} seconds");}catch (OpenEmailNetworkException error) when (error.IsTimeout){ Console.Error.WriteLine("no answer in time");}API からの拒否は OpenEmailApiException をスローし、応答がまったくない場合は OpenEmailNetworkException をスローします。どちらも OpenEmailException から派生しているため、1 つの catch で両方を捕捉でき、when フィルターで種類を選べます。
| プロパティ | 内容 |
|---|---|
| Status | HTTP ステータス。 |
| ErrorType, Code | API のエラー型とコード。たとえば validation_error と invalid_parameter です。 |
| Param | 原因となったフィールド。ある場合のみです。 |
| RequestId | サポートに連絡するときに伝える id です。 |
| DocUrl | そのコードを説明するドキュメントのページです。 |
| RetryAfterSeconds | API が待つよう求めた時間（秒）。 |
| Fields | 登録フォームが拒否したフィールド。それぞれに key と error があります。 |
| Body | デコードされたレスポンスボディです。 |
失敗の種類
| プロパティ | true になる場合 |
|---|---|
| IsAuth | キーまたはトークンが拒否されました。401 です。 |
| IsPermission | この資格情報ではその操作が許可されていません。403 です。 |
| IsScopeMissing | 呼び出しに必要なスコープが資格情報にありません。 |
| IsStepUpRequired | アクセストークンは先にコードを検証する必要があります。 |
| IsNotFound | その id を持つものがありません。404 です。 |
| IsConflict | 変更が現在の状態と競合しています。409 です。 |
| IsValidation | フィールドが拒否されました。422 です。 |
| IsRateLimited | リクエストが多すぎるか、割り当てを使い切りました。429 です。 |
| IsInvalidRequest | リクエストに対するそれ以外の拒否です。 |
| IsServerError | API が失敗しました。ステータスは 500 以上です。 |
| IsRetryable | クライアントが再試行するステータスです。 |
| IsTimeout | タイムアウトまでに応答が届きませんでした。これは OpenEmailNetworkException にあります。 |
形式が正しくないキーや空の ID など、呼び出し自体の誤りは、何も送信される前に ArgumentException をスローします。キャンセルされたトークンは OperationCanceledException をスローし、検証に失敗した Webhook 配信は OpenEmailWebhookException をスローします。
確認コード
アクセストークンはユーザーの代理として動作するため、ドメインの削除のような重要な変更の前に、Web アプリが求めるのと同じ確認コードを求められます。コードを要求し、確認してから、リクエストをもう一度実行してください。API キーがコードを求められることはありません。
var domainId = "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f"; try{ await client.Domains.DeleteAsync(domainId);}catch (OpenEmailApiException error) when (error.IsStepUpRequired){ var challenge = await client.Security.BeginStepUpAsync(); Console.WriteLine($"Enter the code sent by {challenge["method"]}"); await client.Security.VerifyStepUpAsync(new Body { ["code"] = Console.ReadLine()?.Trim() }); await client.Domains.DeleteAsync(domainId);}再試行されるもの
- 読み取り、送信、繰り返しても安全なすべての書き込みは、最大
MaxRetries回まで再試行されます。それ以外の書き込みは 1 回だけ送信されます。 - ステータス 408、500、502、503、504 は、0.5 秒から始まり 8 秒まで倍増する待ち時間をはさんで再試行されます。
- 429 は、1 分以内の
Retry-Afterが付いている場合にだけ再試行され、クライアントはその時間だけ待ちます。 - 失敗した接続やタイムアウトした接続も同じように再試行されます。
再試行される送信は毎回同じ冪等性キーを持つため、API は 2 通目を送らずに最初のメッセージを再生します。