{
  "id": "kafka/connect-rest-api-503-service-unavailable",
  "signature": "HTTP 503 Service Unavailable: Connect REST API is temporarily unavailable due to rebalance",
  "signature_zh": "HTTP 503 Service Unavailable：由于重平衡，Connect REST API暂时不可用",
  "regex": "HTTP 503.*Connect REST API.*rebalance",
  "domain": "kafka",
  "category": "network_error",
  "subcategory": null,
  "root_cause": "Kafka Connect's REST API returns 503 when the cluster is undergoing a rebalance, as worker leadership may be reassigned and endpoints are temporarily disabled.",
  "root_cause_type": "generic",
  "root_cause_zh": "当集群正在进行重平衡时，Kafka Connect的REST API返回503，因为工作节点领导权可能正在重新分配，端点被暂时禁用。",
  "versions": [
    {
      "version": "Kafka 3.4.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Kafka 3.5.1",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Kafka 3.7.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Setting 'rest.advertised.host.name' to a different value",
      "why_fails": "Increasing worker timeout does not prevent the 503 during rebalance; the API is intentionally disabled.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    },
    {
      "action": "Restarting a single Connect worker",
      "why_fails": "Restarting one worker may trigger another rebalance, making the 503 persist longer.",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Implement retry logic with exponential backoff in your client. Example in Python: import time; for i in range(5): try: response = requests.get('http://connect-host:8083/connectors'); break; except requests.exceptions.HTTPError as e: if e.response.status_code == 503: time.sleep(2**i); else: raise",
      "success_rate": 0.93,
      "how": "Implement retry logic with exponential backoff in your client. Example in Python: import time; for i in range(5): try: response = requests.get('http://connect-host:8083/connectors'); break; except requests.exceptions.HTTPError as e: if e.response.status_code == 503: time.sleep(2**i); else: raise",
      "condition": "",
      "sources": []
    },
    {
      "action": "Monitor the rebalance status using Kafka's metrics or logs, and only query the REST API after the rebalance completes. Check for 'REBALANCE_COMPLETED' log entries.",
      "success_rate": 0.85,
      "how": "Monitor the rebalance status using Kafka's metrics or logs, and only query the REST API after the rebalance completes. Check for 'REBALANCE_COMPLETED' log entries.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Implement retry logic with exponential backoff in your client. Example in Python: import time; for i in range(5): try: response = requests.get('http://connect-host:8083/connectors'); break; except requests.exceptions.HTTPError as e: if e.response.status_code == 503: time.sleep(2**i); else: raise",
    "Monitor the rebalance status using Kafka's metrics or logs, and only query the REST API after the rebalance completes. Check for 'REBALANCE_COMPLETED' log entries."
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://kafka.apache.org/documentation/#connect_rest",
  "official_doc_section": null,
  "error_code": "503",
  "verification_tier": "ai_generated",
  "confidence": 0.86,
  "fix_success_rate": 0.79,
  "resolvable": "partial",
  "first_seen": "2024-04-12",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}