Fehler und Wiederholungen
Eine Exception-Klasse für jede Art von Ablehnung und Wiederholungen, die nicht doppelt senden können.
Einen Fehler behandeln
try { client.templates().send("order-shipped", Body.of( "from", "[email protected]", "to", "[email protected]", "props", Body.of("orderId", "AC-4192") ));} catch (ValidationException error) { System.err.println(error.param() + " " + error.getMessage());} catch (RateLimitException error) { System.err.println("Wait " + error.retryAfterSeconds() + " seconds");} catch (ApiException error) { System.err.println(error.status() + " " + error.code() + " " + error.requestId());} catch (NetworkException error) { System.err.println(error.isTimeout() ? "Timed out" : "No response");}Eine Ablehnung der API wirft eine ApiException oder die Unterklasse für ihren Typ, mit dem, was die API dazu gesagt hat. Jede Exception, die der Client wirft, ist eine ungeprüfte OpenEmailException, sodass ein catch sie alle abdeckt.
| Methode | Was sie enthält |
|---|---|
| status() | Der HTTP-Status, oder 0, wenn keine Antwort eintraf. |
| type(), code() | Der Fehlertyp und der Code der API, etwa validation_error und invalid_parameter. |
| param() | Das Feld, das schuld ist, wenn es eines gibt. |
| requestId() | Die ID, die Sie nennen, wenn Sie dem Support schreiben. |
| docUrl() | Die Seite der Dokumentation, die den Code erklärt. |
| retryAfterSeconds() | Wie lange Sie laut API warten sollen. |
| fields() | Die Felder, die ein Anmeldeformular abgelehnt hat, jeweils mit key und error. |
| body() | Der dekodierte Antwortkörper. |
Die Arten von Fehlschlägen
| Exception | Wann sie geworfen wird |
|---|---|
| AuthenticationException | Der Schlüssel oder das Token wurde abgelehnt, mit einem 401. |
| PermissionException | Die Zugangsdaten dürfen das nicht, mit einem 403. |
| NotFoundException | Nichts hat diese ID, mit einem 404. |
| ConflictException | Die Änderung widerspricht dem aktuellen Zustand, mit einem 409. |
| ValidationException | Ein Feld wurde abgelehnt, mit einem 422. |
| RateLimitException | Zu viele Anfragen oder ein Kontingent ist aufgebraucht, mit einem 429. |
| InvalidRequestException | Jede andere Ablehnung der Anfrage. |
| ApiException | Die API ist fehlgeschlagen, mit einem Status von 500 oder höher. |
| NetworkException | Es traf keine Antwort ein. |
| IllegalArgumentException | Der Aufruf selbst war falsch, und nichts wurde gesendet. |
| WebhookSignatureException | Eine Webhook-Zustellung hat ihre Prüfung nicht bestanden. |
Eine ApiException beantwortet auch Fragen über sich selbst: isValidation(), isNotFound(), isRateLimited(), isServerError() und isRetryable(), dazu isScopeMissing(), wenn den Zugangsdaten der Scope fehlt, den der Aufruf braucht, und isStepUpRequired(), wenn ein Zugriffstoken zuerst einen Code bestätigen muss. NetworkException.isTimeout() sagt, dass die Frist abgelaufen ist.
Was erneut versucht wird
- Lesezugriffe, Sendungen und jeder Schreibzugriff, der gefahrlos wiederholt werden kann, werden bis zu
maxRetriesMal erneut versucht. Jeder andere Schreibzugriff wird einmal gesendet. - Die Status 408, 500, 502, 503 und 504 werden mit einer Wartezeit wiederholt, die bei einer halben Sekunde beginnt und sich bis auf acht Sekunden verdoppelt.
- Ein 429 wird nur wiederholt, wenn er ein
Retry-Aftervon höchstens einer Minute trägt, und der Client wartet so lange. - Eine Verbindung, die scheitert oder das Zeitlimit überschreitet, wird genauso wiederholt.
Ein wiederholter Versand trägt jedes Mal denselben Idempotenzschlüssel, sodass die API die erste Nachricht erneut ausgibt, statt eine zweite zu senden.