Introduce failures into HTTP requests via a proxy server
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Chaos HTTP Proxy

Introduce failures into HTTP requests via a proxy server. This can uncover error handling bugs in HTTP clients. Andrew Gaul at Bounce Storage originally wrote Chaos HTTP Proxy.


Chaos HTTP Proxy can trigger many different failures:

  • change case of HTTP header name
  • Content-MD5 request corruption
  • Content-MD5 response corruption
  • client timeout, HTTP 408
  • redirects (temporary and permanent)
  • reorder response headers
  • server connection break, i.e., short read and write
  • server errors: HTTP 500, 503, and 504
  • server timeout


Users can download releases from GitHub. One can also build the project by running mvn package which produces a binary at target/chaos-http-proxy. Chaos HTTP Proxy requires Java 7 to run.


Linux and Mac OS X users can run Chaos HTTP Proxy via the executable jar:

chmod +x chaos-http-proxy
chaos-http-proxy --properties chaos-http-proxy.conf

Windows users must explicitly invoke java:

java -jar chaos-http-proxy --properties chaos-http-proxy.conf

An example using curl:

curl --fail --proxy http://localhost:1080/
curl: (22) The requested URL returned error: 500 Server Error

Configuring Failure Rates

The configuration file determines all possible results for an HTTP request. Entries take the form [response_type]=[n], where [n] is an integral value that determines the relative occurrence likelihood of each response type. For example, the following configuration gives a 1% chance of responses failing with a 500 Internal Error response:


Sample configuration

Chaos HTTP Proxy accepts configuration at invocation time via the --properties flag and at run-time via the /chaos/api endpoint:

curl --request POST --upload-file chaos-http-proxy.conf http://localhost:1080/chaos/api
curl http://localhost:1080/chaos/api


  • lacks HTTP authentication
  • lacks HTTPS support


  • Charles Web Debugging Proxy - allows interactive modification of HTTP requests and responses
  • Chaos Monkey - inspiration for Chaos HTTP Proxy
  • Hamms - designed to elicit failures in your HTTP Client, similar to httpbin
  • httpbin - HTTP Request & Response Service which can deterministically exercise HTTP functionality
  • pathod - programmable HTTP server
  • toxiproxy - A proxy to simulate network and system conditions
  • toxy - Hackable HTTP proxy to simulate server failure scenarios and unexpected network conditions
  • Vaurien - Chaos TCP Proxy


Copyright (C) 2015-2016 Bounce Storage

Licensed under the Apache License, Version 2.0