Hibák
Minden hiba kivételt dob. Két osztály, és minden API-hibán egy kérésazonosító.
Hiba elkapása
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}A küldésen kapott permission_error rendszerint a KULCS küldési hatókörén, egy domainen vagy egy címen múlik, amelyet nem kapott meg, nem pedig a munkaterületen – ezért írja ki a minta, hogy az addresses.list() szerint ez a kulcs milyen néven küldhet.
Az osztályok
| Osztály | Mikor |
|---|---|
| `OpenEmailApiError` | Az API válaszolt, de nem sikerrel. A status, a type, a code, a param, a docUrl, a requestId és a retryAfterSeconds mezőket hordozza. |
| `OpenEmailNetworkError` | Nem érkezett válasz: DNS, TLS, megszakadt kapcsolat, időtúllépés, vagy a saját AbortSignal jelzésed. A cause mezőt hordozza, és az isTimeout igaz, ha az időtúllépés volt az ok. |
| `Error` | Még azelőtt dobódik, hogy bármi elment volna: hiányzó vagy hibás kulcs, használhatatlan baseUrl, böngésző, üres azonosító. |
| Getter | Igaz, ha |
|---|---|
| `isAuth` | A type értéke authentication_error, egy 401: nincs kulcs, rossz típusú hitelesítő adat, vagy olyan kulcs, amelyet nem mi adtunk ki. |
| `isPermission` | permission_error, egy 403: valódi kulcs a szükséges hatókör vagy From cím nélkül. |
| `isScopeMissing` | A code értéke insufficient_scope, az a 403, amely megnevezi a hiányzó hatókört. |
| `isInvalidRequest` | invalid_request_error, egy 400: értelmezhetetlen kérés. A mérethatárt túllépő üzenet 422 message_too_large válasszal tér vissza, így azt az isValidation getter fogja meg. |
| `isValidation` | validation_error, egy 422: a séma utasította el, és a param nevezi meg a mezőt. |
| `isNotFound` | not_found_error, egy 404: nincs ilyen erőforrás. |
| `isConflict` | conflict_error, egy 409: az erőforrás túl van azon a ponton, ahol ezt még el lehetett volna végezni rajta. |
| `isRateLimited` | rate_limit_error, egy 429. A retryAfterSeconds tartalmazza a várakozást, ha a szerver megnevezett egyet. |
| `isServerError` | A status 500 vagy afölötti. Ha az ügyfélszolgálathoz fordulsz, hivatkozz a requestId értékére. |
| `isRetryable` | A status 408, 429, 500, 502, 503 vagy 504. |
A getterek a type mezőt olvassák, a boríték befagyasztott felét. A code string marad, mert az API garantáltan nyitott és bővíthető, így a fel nem ismert kódot a type alapján kezeld. Egy zárt unió esetén egy új hibamód elolvasásának ára egy SDK-frissítés lenne.
Az a törzs, amely nem az API hibaborítékja, szintén OpenEmailApiError lesz: a type az állapotkódból következik, a code pedig unrecognised_response. A nem JSON törzsű sikeres válasz is ilyet dob.
A megszakítás szintén OpenEmailNetworkError, akár a kérés közben, akár az újrapróbálkozás előtti várakozás alatt érkezik, és a megszakítás a cause mezőben marad meg. Ha meg kell különböztetned a saját megszakításodat a hálózati hibától, nézd meg a signal.aborted értékét.
requestId
Minden OpenEmailApiError magával viszi a szerver által küldött kérésazonosítót, a hibatörzsből vagy az x-request-id fejlécből, és ez az egyetlen dolog, ami a hibádat a szerver naplójának egy sorához köti. A sikeres hívás csak a feldolgozott törzzsel tér vissza, így azon nincs kiolvasható kérésazonosító.