はじめに

エラーと再試行

標準のJSONエラーエンベロープを解析し、再試行しても安全なタイミングを判断します。

エラーエンベロープ

JSON APIの失敗時には、トップレベルにerrorオブジェクトが1つ返されます。このオブジェクトには、人が読めるmessage、数値のHTTP status、および任意の安定したcodeが含まれます。OpenAPIの仕様では、想定内・想定外の失敗の両方でこのスキーマを参照しています。

エラーレスポンス
{
  "error": {
    "code": "invalid_request",
    "message": "A verified From domain is required",
    "status": 403
  }
}

クライアントエラー

400の入力エラーは、修正してから再試行してください。401の後は、無効な認証情報を差し替えるか失効させてください。402は有料の利用権が必要であること、403はポリシーまたは権限の境界、404はテナント単位のリソースが存在しないこと、409は状態または冪等性の競合、413は添付ファイルの上限超過を示し、422はバリデーションまたはサプレッションに該当します。

再試行の判断

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.

サポートに必要な情報

リクエスト時刻、ルート、HTTPステータス、SendHQのリソースID、秘密でないエラーフィールドを記録してください。サポートへの報告には、APIキー、セッションCookie、メッセージ本文、受信者リストを絶対に含めないでください。