Fehler
Jeder Fehlschlag löst eine Ausnahme aus. Zwei Klassen und eine Request-ID bei jedem API-Fehler.
Einen Fehler abfangen
from openemail import OpenEmailApiError, OpenEmailNetworkError, openemail try: openemail.emails.send({'from': sender, 'to': recipient, 'subject': subject, 'text': text})except OpenEmailApiError as error: if error.is_validation: print(error.code, error.param, error.message) if error.is_permission: print(openemail.addresses.list()) if error.is_rate_limited: print('try again in', error.retry_after_seconds, 'seconds') print(error.status, error.request_id) raiseexcept OpenEmailNetworkError as error: if error.is_timeout: print('no answer in time') raiseEin 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 message, status, type, code, param, doc_url, request_id, retry_after_seconds, fields und body. |
| OpenEmailNetworkError | Es kam keine Antwort an: DNS, TLS, eine abgebrochene Verbindung oder das Timeout. Trägt cause, die zugrunde liegende httpx-Ausnahme, und is_timeout ist True, wenn das Timeout der Grund war. |
| OpenEmailError | Die Basis beider, sodass ein einziges except jeden Fehlschlag abfängt, den die API oder das Netzwerk verursacht hat. Auch WebhookVerificationError, den verify_webhook_signature auslöst, erbt davon. |
| ValueError | Wird ausgelöst, bevor irgendetwas gesendet wird: ein fehlender oder fehlerhafter Schlüssel, eine unbrauchbare base_url, Anmeldedaten, die über einfaches http gehen sollen, eine leere ID. Ein falscher http_client oder ein Body, den JSON nicht abbilden kann, löst stattdessen TypeError aus. |
fields listet jede Antwort auf, die ein Anmeldeformular abgelehnt hat, als key und error, und ist bei jedem anderen Fehler None. body bewahrt das JSON, das die API gesendet hat, oder ist None, wenn der Body kein JSON war.
| Eigenschaft | True, wenn |
|---|---|
| is_auth | type ist authentication_error, ein 401: kein Schlüssel, die falsche Art von Zugangsdaten oder ein Schlüssel, den wir nicht ausgestellt haben. |
| is_permission | permission_error, ein 403: ein echter Schlüssel ohne den Scope oder die From-Adresse, die er braucht. |
| is_scope_missing | code ist insufficient_scope, der 403, der einen fehlenden Scope nennt. |
| is_invalid_request | 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, is_validation ist daher die Eigenschaft, die sie abfängt. |
| is_validation | validation_error, ein 422: Das Schema hat sie abgelehnt, und param nennt das Feld. |
| is_not_found | not_found_error, ein 404: keine solche Ressource. |
| is_conflict | conflict_error, ein 409: Die Ressource ist über den Punkt hinaus, an dem dies mit ihr möglich wäre. |
| is_rate_limited | rate_limit_error, ein 429. retry_after_seconds enthält die Wartezeit, wenn der Server eine genannt hat. |
| is_server_error | status ist 500 oder höher. Nennen Sie request_id, wenn Sie den Support kontaktieren. |
| is_retryable | status ist 408, 429, 500, 502, 503 oder 504. |
| is_step_up_required | code ist step_up_required, der 403, den ein OAuth-Zugriffstoken vor einer heiklen Änderung bekommt, bis die Person einen Code bestätigt hat. |
Die meisten Eigenschaften lesen type, die eingefrorene Hälfte des Umschlags. code bleibt ein str, weil die API zusichert, dass er offen und erweiterbar ist; behandeln Sie einen unbekannten daher als seinen type. Ein geschlossenes Literal 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, löst ebenfalls einen aus.
Das Abbrechen eines AsyncOpenEmail-Aufrufs löst keinen OpenEmailError aus. Der Abbruch selbst wird weitergereicht, ob er während der Anfrage oder während der Wartezeit vor einer Wiederholung eintrifft, und danach wird nichts wiederholt.
request_id
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 gibt allein den geparsten Body zurück, an ihm gibt es daher keine Request-ID zu lesen.
str(error) endet mit dem Status, dem Code und der Request-ID, eine Logzeile, die die Ausnahme ausgibt, behält also alle drei. Ein OpenEmailApiError übersteht außerdem das Pickling mit allen Feldern, sodass einer, der in einem Worker-Prozess ausgelöst wurde, unversehrt beim Elternprozess ankommt.