Fehler
Jeder Fehlschlag wirft. Zwei Klassen und eine request id bei jedem API-Fehler.
Einen Fehler abfangen
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}Ein permission_error bei einem Versand liegt meist am Sende-Scope des SCHLÜSSELS, an einer Domain oder einer Adresse, die ihm nicht zugestanden wurde, und nicht am Workspace; darum gibt das Beispiel aus, was addresses.list() als zulässige Absenderadressen dieses Schlüssels nennt.
Die Klassen
| Klasse | Wann |
|---|---|
| `OpenEmailApiError` | Die API hat geantwortet, und zwar nicht mit einem Erfolg. Trägt status, type, code, param, docUrl, requestId und retryAfterSeconds. |
| `OpenEmailNetworkError` | Es kam keine Antwort an: DNS, TLS, eine abgebrochene Verbindung, das Timeout oder Ihr eigenes AbortSignal. Trägt cause, und isTimeout ist true, wenn das Timeout der Grund war. |
| `Error` | Wird geworfen, bevor irgendetwas gesendet wird: ein fehlender oder fehlerhafter Schlüssel, eine unbrauchbare baseUrl, ein Browser, eine leere id. |
| Getter | True, wenn |
|---|---|
| `isAuth` | type ist authentication_error, ein 401: kein Schlüssel, die falsche Art von Zugangsdaten oder ein Schlüssel, den wir nicht ausgestellt haben. |
| `isPermission` | permission_error, ein 403: ein echter Schlüssel ohne den Scope oder die From-Adresse, die er braucht. |
| `isScopeMissing` | code ist insufficient_scope, der 403, der einen fehlenden Scope nennt. |
| `isInvalidRequest` | invalid_request_error, ein 400: eine Anfrage, die nicht verstanden werden konnte. Eine Nachricht über der Größenobergrenze kommt als 422 message_too_large zurück, isValidation ist daher der Getter, der sie abfängt. |
| `isValidation` | validation_error, ein 422: Das Schema hat sie abgelehnt, und param nennt das Feld. |
| `isNotFound` | not_found_error, ein 404: keine solche Ressource. |
| `isConflict` | conflict_error, ein 409: Die Ressource ist über den Punkt hinaus, an dem dies mit ihr möglich wäre. |
| `isRateLimited` | rate_limit_error, ein 429. retryAfterSeconds enthält die Wartezeit, wenn der Server eine genannt hat. |
| `isServerError` | status ist 500 oder höher. Nennen Sie requestId, wenn Sie den Support kontaktieren. |
| `isRetryable` | status ist 408, 429, 500, 502, 503 oder 504. |
Die Getter lesen type, die eingefrorene Hälfte des Umschlags. code bleibt ein string, weil die API zusichert, dass er offen und erweiterbar ist; behandeln Sie einen unbekannten daher als seinen type. Eine geschlossene Union würde ein SDK-Upgrade zum Preis dafür machen, einen neuen Fehlerfall lesen zu können.
Ein Body, der nicht dem Fehlerumschlag der API entspricht, wird trotzdem zu einem OpenEmailApiError, wobei type aus dem Status abgeleitet und code auf unrecognised_response gesetzt wird. Ein Erfolg, dessen Body kein JSON ist, wirft ebenfalls einen.
Ein Abbruch ist ebenfalls ein OpenEmailNetworkError, ob er während der Anfrage oder während der Wartezeit vor einem erneuten Versuch eintritt, und der Abbruch wird an cause aufbewahrt. Prüfen Sie signal.aborted, wenn Sie Ihre eigene Stornierung von einem Netzwerkfehler unterscheiden müssen.
requestId
Jeder OpenEmailApiError trägt die vom Server gesendete request id, aus dem Fehler-Body oder dem Header x-request-id, und sie ist das Einzige, was Ihren Fehlschlag mit einer Zeile im Serverlog verbindet. Ein Erfolg löst allein zum geparsten Body auf, an ihm gibt es daher keine request id zu lesen.