Errors
Tota fallada llança una excepció. Dues classes, i un id de petició a cada error de l'API.
Com capturar-ne un
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}Un permission_error en un enviament sol ser l'abast d'enviament de la CLAU, un domini o una adreça que no se li van concedir, més que no pas l'espai de treball; per això l'exemple imprimeix des de quines adreces diu addresses.list() que pot enviar aquesta clau.
Les classes
| Classe | Quan |
|---|---|
| `OpenEmailApiError` | L'API ha respost, i no amb un èxit. Porta status, type, code, param, docUrl, requestId i retryAfterSeconds. |
| `OpenEmailNetworkError` | No ha arribat cap resposta: DNS, TLS, una connexió caiguda, el temps d'espera o el teu propi AbortSignal. Porta cause, i isTimeout és cert quan el motiu ha estat el temps d'espera. |
| `Error` | Es llança abans d'enviar res: una clau absent o mal formada, un baseUrl inservible, un navegador, un id buit. |
| Getter | Cert quan |
|---|---|
| `isAuth` | type és authentication_error, un 401: cap clau, un tipus de credencial equivocat, o una clau que no hem emès nosaltres. |
| `isPermission` | permission_error, un 403: una clau real sense l'abast o l'adreça From que necessita. |
| `isScopeMissing` | code és insufficient_scope, el 403 que anomena un abast que falta. |
| `isInvalidRequest` | invalid_request_error, un 400: una petició que no s'ha pogut entendre. Un missatge per sobre del límit de mida torna com un 422 message_too_large, de manera que isValidation és el getter que el captura. |
| `isValidation` | validation_error, un 422: l'esquema l'ha rebutjat, i param anomena el camp. |
| `isNotFound` | not_found_error, un 404: no existeix aquest recurs. |
| `isConflict` | conflict_error, un 409: el recurs ha passat el punt en què se li podia fer això. |
| `isRateLimited` | rate_limit_error, un 429. retryAfterSeconds conté l'espera quan el servidor n'ha indicat una. |
| `isServerError` | status és 500 o superior. Cita requestId si contactes amb el servei d'assistència. |
| `isRetryable` | status és 408, 429, 500, 502, 503 o 504. |
Els getters llegeixen type, la meitat congelada del sobre. code continua sent un string, perquè l'API garanteix que és obert i additiu; per tant, tracta el que no reconeguis segons el seu type. Una unió tancada faria que actualitzar l'SDK fos el preu de llegir un nou mode de fallada.
Un cos que no sigui el sobre d'error de l'API també esdevé un OpenEmailApiError, amb type inferit a partir de l'estat i code fixat a unrecognised_response. Un èxit el cos del qual no sigui JSON també en llança un.
Una cancel·lació també és un OpenEmailNetworkError, tant si arriba durant la petició com durant l'espera prèvia a un reintent, i la cancel·lació es conserva a cause. Comprova signal.aborted quan necessitis distingir la teva pròpia cancel·lació d'una fallada de xarxa.
requestId
Cada OpenEmailApiError porta l'id de petició que ha enviat el servidor, procedent del cos de l'error o de la capçalera x-request-id, i és l'única cosa que lliga la teva fallada a una línia del registre del servidor. Un èxit es resol només amb el cos analitzat, de manera que en un èxit no hi ha cap id de petició per llegir.