Fehler und Wiederholungen
Ein Ausnahmetyp für jede Ablehnung, eine Eigenschaft für jede Art und Wiederholungen, die nicht doppelt senden können.
Einen Fehler behandeln
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");}Eine Ablehnung der API löst OpenEmailApiException aus, und gar keine Antwort löst OpenEmailNetworkException aus. Beide leiten von OpenEmailException ab, sodass ein catch beide fängt und ein when-Filter die Art auswählt.
| Eigenschaft | Was sie enthält |
|---|---|
| Status | Der HTTP-Status. |
| ErrorType, Code | Der Fehlertyp und der Code der API, etwa validation_error und invalid_parameter. |
| Param | Das Feld, das schuld ist, wenn es eines gibt. |
| RequestId | Die ID, die Sie nennen, wenn Sie dem Support schreiben. |
| DocUrl | Die Seite der Dokumentation, die den Code erklärt. |
| RetryAfterSeconds | Wie lange Sie laut API warten sollen, in Sekunden. |
| Fields | Die Felder, die ein Anmeldeformular abgelehnt hat, jeweils mit key und error. |
| Body | Der dekodierte Antwortkörper. |
Die Arten von Fehlschlägen
| Eigenschaft | Wann sie wahr ist |
|---|---|
| IsAuth | Der Schlüssel oder das Token wurde abgelehnt, mit einem 401. |
| IsPermission | Die Zugangsdaten dürfen das nicht, mit einem 403. |
| IsScopeMissing | Den Zugangsdaten fehlt der Scope, den der Aufruf braucht. |
| IsStepUpRequired | Ein Zugriffstoken muss zuerst einen Code bestätigen. |
| IsNotFound | Nichts hat diese ID, mit einem 404. |
| IsConflict | Die Änderung widerspricht dem aktuellen Zustand, mit einem 409. |
| IsValidation | Ein Feld wurde abgelehnt, mit einem 422. |
| IsRateLimited | Zu viele Anfragen oder ein Kontingent ist aufgebraucht, mit einem 429. |
| IsInvalidRequest | Jede andere Ablehnung der Anfrage. |
| IsServerError | Die API ist fehlgeschlagen, mit einem Status von 500 oder höher. |
| IsRetryable | Der Status gehört zu denen, die der Client erneut versucht. |
| IsTimeout | Vor Ablauf des Zeitlimits kam keine Antwort. Diese Eigenschaft liegt auf OpenEmailNetworkException. |
Ein Fehler im Aufruf selbst, etwa ein fehlerhafter Schlüssel oder eine leere ID, löst ArgumentException aus, bevor irgendetwas gesendet wird. Ein abgebrochenes Token löst OperationCanceledException aus, und eine Webhook-Zustellung, die ihre Prüfung nicht besteht, löst OpenEmailWebhookException aus.
Ein Bestätigungscode
Ein Zugriffstoken handelt für eine Person. Vor einer heiklen Änderung, etwa dem Löschen einer Domain, wird es deshalb nach demselben Bestätigungscode gefragt, den auch die Web-App verlangt. Fordern Sie einen Code an, prüfen Sie ihn und stellen Sie die Anfrage dann erneut. API-Schlüssel werden nie danach gefragt.
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);}Was erneut versucht wird
- Lesezugriffe, Sendungen und jeder Schreibzugriff, der gefahrlos wiederholt werden kann, werden bis zu
MaxRetriesMal erneut versucht. Jeder andere Schreibzugriff wird einmal gesendet. - Die Status 408, 500, 502, 503 und 504 werden mit einer Wartezeit wiederholt, die bei einer halben Sekunde beginnt und sich bis auf acht Sekunden verdoppelt.
- Ein 429 wird nur wiederholt, wenn er ein
Retry-Aftervon höchstens einer Minute trägt, und der Client wartet so lange. - Eine Verbindung, die scheitert oder das Zeitlimit überschreitet, wird genauso wiederholt.
Ein wiederholter Versand trägt jedes Mal denselben Idempotenzschlüssel, sodass die API die erste Nachricht erneut ausgibt, statt eine zweite zu senden.