Heuristic:Mage ai Mage ai HTTP Request Timeout Defaults
| Knowledge Sources | |
|---|---|
| Domains | Optimization, Data_Integration |
| Last Updated | 2026-02-09 07:00 GMT |
Overview
Universal 300-second (5-minute) HTTP request timeout with defensive zero-value handling.
Description
All HTTP-based source connectors in the mage-integrations framework default to a 300-second (5-minute) request timeout. This value is hardcoded as `REQUEST_TIMEOUT = 300` in the base HTTP client and reused across Stripe, Zendesk, and other API connectors. The timeout is configurable via the `request_timeout` config key, but the framework defensively treats falsy values (0, "0", empty string, or missing) as "use the default" rather than "no timeout", preventing accidental infinite hangs.
Usage
Apply this heuristic when:
- Configuring API source connectors: Set `request_timeout` in config to override the 300-second default.
- Debugging hanging extractions: If a source seems stuck, check that the API endpoint responds within 300 seconds.
- Extracting from slow APIs: Increase timeout beyond 300 seconds for APIs with known slow responses (e.g., large report generation).
The Insight (Rule of Thumb)
- Action: Set `request_timeout` in connector config JSON to a positive integer (seconds).
- Value: Default is 300 seconds (5 minutes). Do not set to 0 or empty string.
- Trade-off: Higher timeout = tolerates slow APIs but delays failure detection. Lower timeout = faster failure detection but may time out on legitimate slow responses.
- Defensive handling: Values of `0`, `"0"`, `""`, and `None` are all treated as "use default 300s".
Reasoning
A 5-minute timeout is a pragmatic balance for data integration workloads. Many API endpoints (especially analytics and reporting APIs) take 30-120 seconds to respond when generating large datasets. Setting the default too low (e.g., 30 seconds) would cause false failures; setting it too high (e.g., 30 minutes) would delay detection of actual connectivity issues.
The defensive zero-value handling prevents a common configuration mistake: users setting `"request_timeout": 0` intending "use default" but actually causing `requests.request(timeout=0)`, which would make every request fail immediately.
Code Evidence
Default timeout and defensive handling from `sources/http/client.py:10,155-165`:
REQUEST_TIMEOUT = 300
@utils.ratelimit(100, 60)
def make_request(self, url, method='get', params=None, body=None) -> Dict:
...
config_request_timeout = self.config.get('request_timeout')
if config_request_timeout and float(config_request_timeout):
request_timeout = float(config_request_timeout)
else:
# If value is 0,"0","" or not passed then set default to 300 seconds.
request_timeout = REQUEST_TIMEOUT
Rate limit decorator from `sources/http/client.py:155`:
@utils.ratelimit(100, 60)
def make_request(self, url, method='get', params=None, body=None) -> Dict: