Erros
Todas as falhas lançam exceção. Duas classes, e um id de pedido em todos os erros da API.
Apanhar um
import { OpenEmailApiError, OpenEmailNetworkError, openemail } from '@openemail/sdk' try { await openemail.emails.send(message)} catch (error) { if (error instanceof OpenEmailApiError) { if (error.isValidation) console.error(error.code, error.param, error.message) if (error.isPermission) console.error(await openemail.addresses.list()) if (error.isRateLimited) console.error('try again in', error.retryAfterSeconds, 'seconds') console.error(error.status, error.requestId) } if (error instanceof OpenEmailNetworkError && error.isTimeout) console.error('no answer in time') throw error}Um 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 status, type, code, param, docUrl, requestId e retryAfterSeconds. |
| `OpenEmailNetworkError` | Não chegou resposta: DNS, TLS, uma ligação caída, o timeout, ou o seu próprio AbortSignal. Traz cause, e isTimeout é true quando o timeout foi a razão. |
| `Error` | Lançado antes de seja o que for ser enviado: uma chave em falta ou malformada, um baseUrl inutilizável, um browser, um id vazio. |
| Getter | True quando |
|---|---|
| `isAuth` | type é authentication_error, um 401: sem chave, o tipo errado de credencial, ou uma chave que não emitimos. |
| `isPermission` | permission_error, um 403: uma chave real sem o âmbito ou o endereço From de que precisa. |
| `isScopeMissing` | code é insufficient_scope, o 403 que nomeia um âmbito em falta. |
| `isInvalidRequest` | 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 isValidation é o getter que a apanha. |
| `isValidation` | validation_error, um 422: o esquema recusou-o, e param nomeia o campo. |
| `isNotFound` | not_found_error, um 404: não existe tal recurso. |
| `isConflict` | conflict_error, um 409: o recurso já passou o ponto em que isto lhe podia ser feito. |
| `isRateLimited` | rate_limit_error, um 429. retryAfterSeconds contém a espera quando o servidor indicou uma. |
| `isServerError` | status é 500 ou superior. Cite requestId se contactar o suporte. |
| `isRetryable` | status é 408, 429, 500, 502, 503 ou 504. |
Os getters leem type, a metade congelada do envelope. code continua a ser uma string, porque a API garante que é aberto e aditivo, por isso trate um que não reconheça como o seu type. Uma união fechada 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.
Um aborto é também um OpenEmailNetworkError, quer ocorra durante o pedido quer durante a espera antes de uma repetição, e o aborto fica guardado em cause. Verifique signal.aborted quando precisar de distinguir o seu próprio cancelamento de uma falha de rede.
requestId
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 resolve apenas para o corpo analisado, por isso não há nele nenhum id de pedido para ler.