Erreurs et nouvelles tentatives
Un seul type d'exception pour chaque refus, une propriété pour chaque genre, et des nouvelles tentatives qui ne peuvent pas envoyer deux fois.
Gérer une erreur
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");}Un refus de l'API lève OpenEmailApiException, et l'absence totale de réponse lève OpenEmailNetworkException. Les deux dérivent d'OpenEmailException : un seul catch attrape donc l'une comme l'autre, et un filtre when choisit le genre.
| Propriété | Ce qu'il contient |
|---|---|
| Status | Le statut HTTP. |
| ErrorType, Code | Le type d'erreur et le code de l'API, comme validation_error et invalid_parameter. |
| Param | Le champ en cause, quand il y en a un. |
| RequestId | L'identifiant à citer quand vous écrivez au support. |
| DocUrl | La page de la documentation qui explique le code. |
| RetryAfterSeconds | Le temps que l'API vous a demandé d'attendre, en secondes. |
| Fields | Les champs qu'un formulaire d'inscription a refusés, chacun avec une key et une error. |
| Body | Le corps de la réponse, décodé. |
Les genres d'échec
| Propriété | Quand elle est vraie |
|---|---|
| IsAuth | La clé ou le jeton a été refusé, avec un 401. |
| IsPermission | L'identifiant n'a pas le droit de faire cela, avec un 403. |
| IsScopeMissing | Il manque à l'identifiant la portée dont l'appel a besoin. |
| IsStepUpRequired | Un jeton d'accès doit d'abord valider un code. |
| IsNotFound | Rien ne porte cet identifiant, avec un 404. |
| IsConflict | Le changement entre en conflit avec l'état actuel, avec un 409. |
| IsValidation | Un champ a été refusé, avec un 422. |
| IsRateLimited | Trop de requêtes, ou un quota est épuisé, avec un 429. |
| IsInvalidRequest | Tout autre refus de la requête. |
| IsServerError | L'API a échoué, avec un statut de 500 ou plus. |
| IsRetryable | Le statut fait partie de ceux que le client retente. |
| IsTimeout | Aucune réponse n'est arrivée avant la fin du délai. Celle-ci se trouve sur OpenEmailNetworkException. |
Une erreur dans l'appel lui-même, comme une clé mal formée ou un identifiant vide, lève ArgumentException avant tout envoi. Un jeton annulé lève OperationCanceledException, et une livraison de webhook qui échoue à sa vérification lève OpenEmailWebhookException.
Un code de vérification
Un jeton d'accès agit pour une personne : avant un changement sensible, comme la suppression d'un domaine, on lui demande donc le même code de vérification que celui que demande l'application web. Demandez un code, vérifiez-le, puis refaites la requête. On ne demande jamais de code aux clés 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);}Ce qui est retenté
- Les lectures, les envois et toute écriture qui peut être répétée sans risque sont retentés, jusqu'à
MaxRetriesfois. Toute autre écriture est envoyée une seule fois. - Les statuts 408, 500, 502, 503 et 504 sont retentés avec une attente qui commence à une demi-seconde et double jusqu'à huit secondes.
- Un 429 n'est retenté que s'il porte un
Retry-Afterd'une minute ou moins, et le client attend ce temps. - Une connexion qui échoue ou qui dépasse le délai est retentée de la même façon.
Un envoi retenté porte chaque fois la même clé d'idempotence : l'API rejoue donc le premier message au lieu d'en envoyer un second.