Network Throttling

Network throttling lets you artificially degrade the network conditions experienced by your application, without changing your infrastructure or network environment. You can add latency, cap bandwidth, randomly drop connections, or simulate a complete network outage — all scoped to specific requests through the rule engine.

Four throttling actions

HTTPeep provides four distinct actions for simulating different failure modes. Each can be applied as a request action (affecting the outbound request) or as a response action (affecting the inbound response).

Delay

Adds a fixed or variable number of milliseconds to the request or response. Use this to simulate high-latency conditions such as mobile networks, cross-region API calls, or database-backed endpoints with slow queries.

responseActions:
  - type: delay_response
    id: action_1775140499860
    enabled: true
    delayMs: 500

You can configure:

• Fixed delay — always wait exactly N milliseconds
• Random delay — wait a random duration within a specified range

Throttle

Limits the transfer rate of a request or response to a specified bandwidth. This simulates constrained network connections without completely blocking traffic.

responseActions:
  - type: throttle_response
    id: action_1775591855867
    enabled: true
    speed:
      max: 384
      burst: 768

Random Failure

Randomly drops a percentage of matching requests, simulating the kind of intermittent network errors that are common in distributed systems and unreliable mobile connections.

requestActions:
  - type: random_failure
    id: action_rand_fail
    enabled: true
    failureRate: 0.3

A failureRate of 0.3 means approximately 30% of matching requests fail with a connection error. The client receives a network-level failure, not an HTTP error response.

Disconnect

Immediately drops the TCP connection for matching requests, simulating a complete loss of network connectivity. The client receives a connection reset error with no HTTP response.

requestActions:
  - type: disconnect
    id: action_disconnect
    enabled: true

This is different from a 5xx response: Disconnect causes a transport-level failure, not an application-level one. Your application's error handling must deal with a connection error rather than an HTTP status code.

Applying throttling through the rule engine

All throttling actions integrate with the full rule pipeline. You can scope them to specific domains, paths, or request methods:

- id: rule_throttle_api
  description: "Simulate slow mobile network on API calls"
  enabled: true
  builtin: false
  stopAfterMatched: false
  match:
    domains:
      - type: wildcard
        value: "*.example.com"
    originProtocol: https
  requestActions: []
  resolve:
    type: pass_through
  responseActions:
    - type: delay_response
      id: action_delay
      enabled: true
      delayMs: 800
    - type: throttle_response
      id: action_throttle
      enabled: true
      speed:
        max: 512
        burst: 1024

Combining actions

You can chain multiple throttling actions in a single rule. For example, combine Delay and Throttle to simulate a high-latency, low-bandwidth connection:

responseActions:
  - type: delay_response
    id: action_delay
    enabled: true
    delayMs: 300
  - type: throttle_response
    id: action_throttle
    enabled: true
    speed:
      max: 1000
      burst: 2000

responseActions:
  - type: delay_response
    id: action_delay
    enabled: true
    delayMs: 1500
  - type: throttle_response
    id: action_throttle
    enabled: true
    speed:
      max: 50
      burst: 100

requestActions:
  - type: random_failure
    id: action_rand
    enabled: true
    failureRate: 0.2
  - type: delay_request
    id: action_delay
    enabled: true
    delayMs: 200

Common use cases