API Connection Timeout (Error: MKF-TMS-28)

Article #28 📂 Category: Developer & API 🕒 Updated: Nov 14, 2024 👁️ 4,829 views

Error MKF-TMS-28 indicates that the MarketFlow API gateway failed to establish a stable connection within the expected 30-second window. This commonly occurs during bulk listing uploads, webhook deliveries, or dashboard data sync operations.

⚠️ Before proceeding: Ensure you are using the latest MarketFlow SDK version (v3.4.2+) and that your firewall isn't blocking ports 443 or 8443.

1. Verify Network & DNS Resolution

Timeouts often stem from DNS misconfigurations or unstable proxy settings. Run the following diagnostic to confirm connectivity to our API endpoints:

curl -v https://api.marketflow.com/v3/status
nslookup api.marketflow.com
ping -c 4 gateway.marketflow.com

If curl hangs or returns operation timed out, check your corporate proxy or router DNS settings. Switching to 8.8.8.8 or 1.1.1.1 typically resolves this.

2. Rotate API Credentials & Check Rate Limits

Expired tokens or hitting the 1,200 requests/minute limit will cause the gateway to drop connections gracefully, triggering TMS-28. Log into your Developer Dashboard and:

  • Verify your API key hasn't expired or been revoked
  • Check the Rate Limit Monitor for recent throttling events
  • Generate a new key if rotation is older than 90 days
✅ Tip: Implement exponential backoff in your retry logic. MarketFlow returns HTTP 429 before enforcing hard timeouts.

3. Clear Local Session & Cache

Stale local state can cause handshake failures. Clear your development environment's cache using:

marketflow-cli auth:clear
marketflow-cli cache:flush --force
rm -rf ~/.marketflow/cache/*

4. Test with Minimal Payload

Large payloads (>5MB) or malformed JSON structures can stall the parser. Test with a minimal request to isolate the issue:

curl -X POST https://api.marketflow.com/v3/listings/test \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"name": "Connection Test", "type": "diagnostic"}'

If this succeeds, the issue lies in your payload structure or upload chunking strategy.

5. Enable Verbose Logging & Contact Support

If the error persists after these steps, enable debug mode and capture the full trace:

export MKF_LOG_LEVEL=debug
node your_script.js 2>&1 | tee mkf-tms-28-trace.log

Attach the log file and your Request ID (found in response headers as X-MKF-Req-ID) when submitting a ticket.