Erros
Todas as falhas lançam exceção. Duas classes, e um id de pedido em todos os erros da API.
Apanhar um
from openemail import OpenEmailApiError, OpenEmailNetworkError, openemail try: openemail.emails.send({'from': sender, 'to': recipient, 'subject': subject, 'text': text})except OpenEmailApiError as error: if error.is_validation: print(error.code, error.param, error.message) if error.is_permission: print(openemail.addresses.list()) if error.is_rate_limited: print('try again in', error.retry_after_seconds, 'seconds') print(error.status, error.request_id) raiseexcept OpenEmailNetworkError as error: if error.is_timeout: print('no answer in time') raiseUm permission_error num envio é normalmente o âmbito de envio da CHAVE, um domínio ou um endereço que não lhe foi concedido, e não a workspace, e é por isso que o exemplo imprime o que addresses.list() diz que esta chave pode usar para enviar.
As classes
| Classe | Quando |
|---|---|
| OpenEmailApiError | A API respondeu, e não com sucesso. Traz message, status, type, code, param, doc_url, request_id, retry_after_seconds, fields e body. |
| OpenEmailNetworkError | Não chegou resposta: DNS, TLS, uma ligação caída ou o timeout. Traz cause, a exceção de httpx subjacente, e is_timeout é True quando o timeout foi a razão. |
| OpenEmailError | A base de ambas, por isso um único except apanha todas as falhas causadas pela API ou pela rede. WebhookVerificationError, que verify_webhook_signature lança, também herda dela. |
| ValueError | Lançado antes de qualquer coisa ser enviada: uma chave em falta ou malformada, um base_url inutilizável, uma credencial destinada a http simples, um id vazio. Um http_client errado, ou um corpo que o JSON não consegue representar, lança TypeError em vez disso. |
fields lista cada resposta que um formulário de inscrição recusou, como key e error, e é None em qualquer outro erro. body guarda o JSON que a API enviou, ou None quando o corpo não era JSON.
| Propriedade | True quando |
|---|---|
| is_auth | type é authentication_error, um 401: sem chave, o tipo errado de credencial, ou uma chave que não emitimos. |
| is_permission | permission_error, um 403: uma chave real sem o âmbito ou o endereço From de que precisa. |
| is_scope_missing | code é insufficient_scope, o 403 que nomeia um âmbito em falta. |
| is_invalid_request | invalid_request_error, um 400: um pedido que não pôde ser compreendido. Uma mensagem acima do limite de tamanho volta como um 422 message_too_large, por isso is_validation é a propriedade que a apanha. |
| is_validation | validation_error, um 422: o esquema recusou-o, e param nomeia o campo. |
| is_not_found | not_found_error, um 404: não existe tal recurso. |
| is_conflict | conflict_error, um 409: o recurso já passou o ponto em que isto lhe podia ser feito. |
| is_rate_limited | rate_limit_error, um 429. retry_after_seconds contém a espera quando o servidor indicou uma. |
| is_server_error | status é 500 ou superior. Cite request_id se contactar o suporte. |
| is_retryable | status é 408, 429, 500, 502, 503 ou 504. |
| is_step_up_required | code é step_up_required, o 403 que um token de acesso OAuth recebe antes de uma alteração sensível até a pessoa ter verificado um código. |
A maioria das propriedades lê type, a metade congelada do envelope. code continua a ser um str, porque a API garante que é aberto e aditivo, por isso trate um que não reconheça como o seu type. Um Literal fechado faria de uma atualização do SDK o preço de ler um novo modo de falha.
Um corpo que não seja o envelope de erro da API torna-se na mesma um OpenEmailApiError, com type inferido a partir do estado e code definido como unrecognised_response. Um sucesso cujo corpo não seja JSON lança um também.
Cancelar uma chamada de AsyncOpenEmail não lança nenhum OpenEmailError. É o próprio cancelamento que se propaga, quer ocorra durante o pedido quer durante a espera antes de uma repetição, e nada é repetido depois dele.
request_id
Todos os OpenEmailApiError transportam o id de pedido que o servidor enviou, vindo do corpo do erro ou do cabeçalho x-request-id, e é a única coisa que liga a sua falha a uma linha no log do servidor. Um sucesso devolve apenas o corpo analisado, por isso não há nele nenhum id de pedido para ler.
str(error) termina com o estado, o código e o id de pedido, por isso uma linha de log que imprima a exceção mantém os três. Um OpenEmailApiError também pode ser serializado com pickle sem perder nenhum campo, por isso um que seja lançado num processo worker chega intacto ao processo pai.