Erste Schritte

Fehler und Wiederholungsversuche

Das standardisierte JSON-Fehlerobjekt auswerten und entscheiden, wann ein Wiederholungsversuch sicher ist.

Fehlerobjekt

Fehlgeschlagene JSON-API-Aufrufe liefern ein einziges error-Objekt auf oberster Ebene mit einer lesbaren message, dem numerischen HTTP-status und einem optionalen stabilen code. Der OpenAPI-Vertrag verweist für erwartete und unerwartete Fehler auf dieses Schema.

Fehlerantwort
{
  "error": {
    "code": "invalid_request",
    "message": "A verified From domain is required",
    "status": 403
  }
}

Client-Fehler

Korrigieren Sie Eingabefehler mit 400, bevor Sie es erneut versuchen. Ersetzen oder widerrufen Sie ungültige Zugangsdaten nach einem 401. Ein 402 erfordert eine kostenpflichtige Berechtigung, 403 kennzeichnet eine Richtlinien- oder Berechtigungsgrenze, 404 steht für eine fehlende Ressource im Mandantenbereich, 409 für einen Status- oder Idempotenzkonflikt, 413 für überschrittene Anhangslimits, und 422 umfasst Validierung und Sperrliste.

Entscheidungen über Wiederholungsversuche

Do not automatically retry authentication, validation, suppression, conflict, or 402 subscription_required failures. A 402 means the workspace has no active subscription; choose a plan, then send. A 423 with code sender_paused means the exact From identity is paused. A 423 with code account_paused means the workspace is paused for review: the body includes the measured bounce and complaint rates and the limits they crossed (bounce_rate vs bounce_limit, complaint_rate vs complaint_limit). Stop that stream. A 429 with code daily_limit_reached is the workspace daily ladder, not a short backoff. Wait until resets_at (midnight UTC). Retry-After is the seconds until then. hourly_limit_reached waits until the next UTC hour. gmail_recipient_limit waits until midnight UTC. The refused message was not queued. Other 429 responses (quota_exhausted) wait until that monthly, per-sender, or attachment limit resets. A caller may retry a transient 502 or 503 with bounded exponential backoff and jitter. Preserve the same Idempotency-Key and identical JSON payload when retrying one logical send.

Kontext für den Support

Notieren Sie Zeitpunkt der Anfrage, Route, HTTP-Status, SendHQ-Ressourcen-ID und nicht geheime Fehlerfelder. Geben Sie in einer Supportanfrage niemals einen API-Schlüssel, ein Session-Cookie, einen Nachrichteninhalt oder eine Empfängerliste an.