Chyby
Každé selhání vyhodí výjimku. Dvě třídy a u každé chyby API i id požadavku.
Jak chybu zachytit
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}permission_error při odesílání bývá obvykle věcí rozsahu odesílání daného KLÍČE – domény nebo adresy, kterou nedostal – a ne pracovního prostoru; proto ukázka vypisuje, z čeho podle addresses.list() tento klíč smí odesílat.
Třídy
| Třída | Kdy |
|---|---|
| `OpenEmailApiError` | API odpovědělo, a ne úspěchem. Nese status, type, code, param, docUrl, requestId a retryAfterSeconds. |
| `OpenEmailNetworkError` | Nepřišla žádná odpověď: DNS, TLS, přerušené spojení, vypršení časového limitu nebo váš vlastní AbortSignal. Nese cause a isTimeout je true, pokud důvodem bylo vypršení limitu. |
| `Error` | Vyhozeno ještě předtím, než se cokoli odešle: chybějící nebo špatně utvořený klíč, nepoužitelná baseUrl, prohlížeč, prázdné id. |
| Getter | True, když |
|---|---|
| `isAuth` | type je authentication_error, tedy 401: žádný klíč, nesprávný druh přihlašovacího údaje nebo klíč, který jsme nevydali. |
| `isPermission` | permission_error, tedy 403: platný klíč bez potřebného scope nebo bez potřebné adresy From. |
| `isScopeMissing` | code je insufficient_scope, tedy 403, která pojmenovává chybějící scope. |
| `isInvalidRequest` | invalid_request_error, tedy 400: požadavek, kterému nešlo porozumět. Zpráva nad velikostním stropem se vrací jako 422 message_too_large, takže getter, který ji zachytí, je isValidation. |
| `isValidation` | validation_error, tedy 422: schéma požadavek odmítlo a param pojmenovává pole. |
| `isNotFound` | not_found_error, tedy 404: takový zdroj neexistuje. |
| `isConflict` | conflict_error, tedy 409: zdroj je už za bodem, kdy s ním šlo tohle udělat. |
| `isRateLimited` | rate_limit_error, tedy 429. retryAfterSeconds obsahuje dobu čekání, pokud ji server uvedl. |
| `isServerError` | status je 500 nebo vyšší. Pokud se obrátíte na podporu, uveďte requestId. |
| `isRetryable` | status je 408, 429, 500, 502, 503 nebo 504. |
Gettery čtou type, zmrazenou polovinu obálky. code zůstává řetězcem, protože API zaručuje, že je otevřený a jen se rozšiřuje, takže kód, který neznáte, zpracujte podle jeho type. Uzavřený sjednocený typ by z aktualizace SDK udělal cenu za to, že si přečtete nový druh selhání.
Tělo, které není chybovou obálkou API, se přesto stane OpenEmailApiError s type odvozeným ze stavového kódu a code nastaveným na unrecognised_response. Úspěšná odpověď, jejíž tělo není JSON, vyhodí totéž.
Přerušení je rovněž OpenEmailNetworkError, ať už přijde během požadavku, nebo během čekání před opakováním, a samotné přerušení se uchová v cause. Když potřebujete odlišit vlastní zrušení od síťového selhání, zkontrolujte signal.aborted.
requestId
Každá OpenEmailApiError nese id požadavku, které server poslal, ať už z chybového těla, nebo z hlavičky x-request-id, a je to jediné, co vaše selhání váže k řádku v logu serveru. Úspěšná odpověď se vyhodnotí pouze na rozparsované tělo, takže na ní žádné id požadavku ke čtení není.