Erros e novas tentativas
Um único tipo de exceção para cada recusa, uma propriedade para cada género e novas tentativas que não podem enviar duas vezes.
Tratar um erro
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");}Uma recusa da API lança OpenEmailApiException, e a ausência total de resposta lança OpenEmailNetworkException. Ambas derivam de OpenEmailException, por isso um só catch apanha qualquer uma, e um filtro when escolhe o género.
| Propriedade | O que contém |
|---|---|
| Status | O estado HTTP. |
| ErrorType, Code | O tipo de erro e o código da API, como validation_error e invalid_parameter. |
| Param | O campo responsável, quando existe. |
| RequestId | O id a indicar quando escrever ao suporte. |
| DocUrl | A página da documentação que explica o código. |
| RetryAfterSeconds | Quanto tempo a API lhe pediu para esperar, em segundos. |
| Fields | Os campos que um formulário de inscrição recusou, cada um com uma key e um error. |
| Body | O corpo da resposta, descodificado. |
Os géneros de falha
| Propriedade | Quando é verdadeira |
|---|---|
| IsAuth | A chave ou o token foi recusado, com um 401. |
| IsPermission | A credencial não pode fazer isto, com um 403. |
| IsScopeMissing | Falta à credencial o âmbito de que a chamada precisa. |
| IsStepUpRequired | Um token de acesso tem primeiro de verificar um código. |
| IsNotFound | Nada tem esse id, com um 404. |
| IsConflict | A alteração entra em conflito com o estado atual, com um 409. |
| IsValidation | Um campo foi recusado, com um 422. |
| IsRateLimited | Demasiados pedidos, ou uma quota esgotou-se, com um 429. |
| IsInvalidRequest | Qualquer outra recusa do pedido. |
| IsServerError | A API falhou, com um estado de 500 ou superior. |
| IsRetryable | O estado é um dos que o cliente tenta de novo. |
| IsTimeout | Não chegou nenhuma resposta antes do tempo limite. Esta está em OpenEmailNetworkException. |
Um erro na própria chamada, como uma chave mal formada ou um id vazio, lança ArgumentException antes de qualquer envio. Um token cancelado lança OperationCanceledException, e uma entrega de webhook que falha a verificação lança OpenEmailWebhookException.
Um código de verificação
Um token de acesso age em nome de uma pessoa, por isso, antes de uma alteração sensível, como eliminar um domínio, é-lhe pedido o mesmo código de verificação que a aplicação web pede. Peça um código, verifique-o e volte a fazer o pedido. Às chaves de API nunca é pedido nenhum.
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);}O que é tentado de novo
- As leituras, os envios e todas as escritas que é seguro repetir são tentados de novo, até
MaxRetriesvezes. Qualquer outra escrita é enviada uma só vez. - Os estados 408, 500, 502, 503 e 504 são tentados de novo com uma espera que começa em meio segundo e duplica até oito segundos.
- Um 429 só é tentado de novo quando traz um
Retry-Afterde um minuto ou menos, e o cliente espera esse tempo. - Uma ligação que falha ou que excede o tempo limite é tentada de novo da mesma forma.
Um envio tentado de novo leva sempre a mesma chave de idempotência, por isso a API repete a primeira mensagem em vez de enviar uma segunda.