Fouten
Elke fout gooit. Twee klassen, en een request-id op elke API-fout.
Er een opvangen
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}Een permission_error bij een verzending komt meestal door de verzendscope van de SLEUTEL, een domein of een adres dat hij niet gekregen heeft, en niet door de workspace, en daarom drukt het voorbeeld af wat addresses.list() zegt dat deze sleutel als afzender mag gebruiken.
De klassen
| Klasse | Wanneer |
|---|---|
| `OpenEmailApiError` | De API antwoordde, en niet met een succes. Draagt status, type, code, param, docUrl, requestId en retryAfterSeconds. |
| `OpenEmailNetworkError` | Er kwam geen antwoord: DNS, TLS, een verbroken verbinding, de timeout, of je eigen AbortSignal. Draagt cause, en isTimeout is waar wanneer de timeout de reden was. |
| `Error` | Gegooid voordat er iets verstuurd is: een ontbrekende of misvormde sleutel, een onbruikbare baseUrl, een browser, een lege id. |
| Getter | Waar wanneer |
|---|---|
| `isAuth` | type is authentication_error, een 401: geen sleutel, het verkeerde soort credential, of een sleutel die wij niet hebben uitgegeven. |
| `isPermission` | permission_error, een 403: een echte sleutel zonder de scope of het From-adres dat hij nodig heeft. |
| `isScopeMissing` | code is insufficient_scope, de 403 die een ontbrekende scope noemt. |
| `isInvalidRequest` | invalid_request_error, een 400: een verzoek dat niet begrepen kon worden. Een bericht boven het groottemaximum komt terug als een 422 message_too_large, dus isValidation is de getter die dat opvangt. |
| `isValidation` | validation_error, een 422: het schema weigerde het, en param noemt het veld. |
| `isNotFound` | not_found_error, een 404: geen zodanige resource. |
| `isConflict` | conflict_error, een 409: de resource is voorbij het punt waarop dit er nog mee gedaan kan worden. |
| `isRateLimited` | rate_limit_error, een 429. retryAfterSeconds bevat de wachttijd wanneer de server er een noemde. |
| `isServerError` | status is 500 of hoger. Vermeld requestId als je contact opneemt met support. |
| `isRetryable` | status is 408, 429, 500, 502, 503 of 504. |
De getters lezen type, de vastliggende helft van de envelop. code blijft een string, omdat de API garandeert dat die open en aanvullend is, dus behandel een code die je niet herkent als zijn type. Een gesloten union zou een SDK-upgrade de prijs maken van het lezen van een nieuwe faalwijze.
Een body die niet de foutenvelop van de API is wordt alsnog een OpenEmailApiError, met type afgeleid uit de status en code op unrecognised_response. Een succes waarvan de body geen JSON is gooit er ook een.
Een afbreking is eveneens een OpenEmailNetworkError, of die nu tijdens het verzoek of tijdens het wachten voor een herhaling valt, en de afbreking wordt op cause bewaard. Controleer signal.aborted wanneer je je eigen annulering van een netwerkfout moet onderscheiden.
requestId
Elke OpenEmailApiError draagt de request-id die de server stuurde, uit de foutbody of de x-request-id-header, en dat is het enige dat je fout verbindt met een regel in het logboek van de server. Een succes lost op tot alleen de geparseerde body, dus daarop is geen request-id te lezen.