Documentation

Everything you need to integrate Request Proxy into your application

Core Headers

These headers are required for every request through Request Proxy.

Request Headers

HeaderRequiredDescription
Request-Proxy-KeyYesYour API key from the dashboard
Request-Proxy-HostYesTarget API hostname (e.g., api.example.com)

Response Headers

HeaderDescription
X-Request-Proxy-Request-IdUUID for request tracing and debugging
X-Request-Proxy-Latency-MsTotal request duration in milliseconds
X-Request-Proxy-Upstream-ErrorPresent ("true") when the error originated from the upstream target, not from Request Proxy

Error Responses

StatusErrorDescription
400Missing Request-Proxy-HostTarget host header is required
401Invalid API keyAPI key not found or malformed
403API key disabledYour API key has been disabled
403Request quota exhaustedUpgrade your plan or wait for reset
429Rate limit exceededToo many requests, slow down

Code Examples

curl -X GET "https://api.requestproxy.com/v1/users" \
  -H "Request-Proxy-Key: al_live_abc123" \
  -H "Request-Proxy-Host: api.example.com" \
  -H "Authorization: Bearer your-target-api-token"

import requests

response = requests.get(
    "https://api.requestproxy.com/v1/users",
    headers={
        "Request-Proxy-Key": "al_live_abc123",
        "Request-Proxy-Host": "api.example.com",
        "Authorization": "Bearer your-target-api-token",
    }
)

print(f"Request ID: {response.headers['X-Request-Proxy-Request-Id']}")
print(response.json())

const response = await fetch("https://api.requestproxy.com/v1/users", {
  headers: {
    "Request-Proxy-Key": "al_live_abc123",
    "Request-Proxy-Host": "api.example.com",
    "Authorization": "Bearer your-target-api-token",
  },
});

console.log("Request ID:", response.headers.get("X-Request-Proxy-Request-Id"));
const data = await response.json();

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.requestproxy.com/v1/users"))
    .header("Request-Proxy-Key", "al_live_abc123")
    .header("Request-Proxy-Host", "api.example.com")
    .header("Authorization", "Bearer your-target-api-token")
    .GET()
    .build();

HttpResponse<String> response = client.send(
    request, HttpResponse.BodyHandlers.ofString());

System.out.println("Request ID: " +
    response.headers().firstValue("X-Request-Proxy-Request-Id").orElse(""));

import Network.HTTP.Simple

main :: IO ()
main = do
  let request = setRequestHeader "Request-Proxy-Key" ["al_live_abc123"]
              $ setRequestHeader "Request-Proxy-Host" ["api.example.com"]
              $ setRequestHeader "Authorization" ["Bearer your-target-api-token"]
              $ "GET https://api.requestproxy.com/v1/users"

  response <- httpBS request
  let requestId = getResponseHeader "X-Request-Proxy-Request-Id" response
  print requestId
  print (getResponseBody response)

Retries

Request Proxy automatically retries failed requests with configurable backoff strategies.

Request Headers

HeaderRequiredDescription
Request-Proxy-Max-Retries3Maximum retry attempts (0-10)
Request-Proxy-Retry-BackoffexponentialBackoff strategy: exponential, linear, or fixed
Request-Proxy-Timeout30000Request timeout in milliseconds
  • exponential(default): Delays double each retry (1s, 2s, 4s, 8s...)
  • linear: Fixed delay increase (1s, 2s, 3s, 4s...)
  • fixed: Same delay between each retry (1s, 1s, 1s...)

Response Headers

HeaderDescription
X-Request-Proxy-RetriesNumber of retry attempts performed

Error Responses

StatusErrorDescription
503Circuit breaker openTarget API is failing repeatedly, try again later

Code Examples

curl -X GET "https://api.requestproxy.com/v1/users" \
  -H "Request-Proxy-Key: al_live_abc123" \
  -H "Request-Proxy-Host: api.example.com" \
  -H "Request-Proxy-Max-Retries: 5" \
  -H "Request-Proxy-Retry-Backoff: exponential" \
  -H "Request-Proxy-Timeout: 60000"

import requests

response = requests.get(
    "https://api.requestproxy.com/v1/users",
    headers={
        "Request-Proxy-Key": "al_live_abc123",
        "Request-Proxy-Host": "api.example.com",
        "Request-Proxy-Max-Retries": "5",
        "Request-Proxy-Retry-Backoff": "exponential",
        "Request-Proxy-Timeout": "60000",
    }
)

retries = response.headers.get("X-Request-Proxy-Retries", "0")
print(f"Request completed after {retries} retries")

const response = await fetch("https://api.requestproxy.com/v1/users", {
  headers: {
    "Request-Proxy-Key": "al_live_abc123",
    "Request-Proxy-Host": "api.example.com",
    "Request-Proxy-Max-Retries": "5",
    "Request-Proxy-Retry-Backoff": "exponential",
    "Request-Proxy-Timeout": "60000",
  },
});

const retries = response.headers.get("X-Request-Proxy-Retries") ?? "0";
console.log(`Request completed after ${retries} retries`);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.requestproxy.com/v1/users"))
    .header("Request-Proxy-Key", "al_live_abc123")
    .header("Request-Proxy-Host", "api.example.com")
    .header("Request-Proxy-Max-Retries", "5")
    .header("Request-Proxy-Retry-Backoff", "exponential")
    .header("Request-Proxy-Timeout", "60000")
    .GET()
    .build();

HttpResponse<String> response = client.send(
    request, HttpResponse.BodyHandlers.ofString());

String retries = response.headers()
    .firstValue("X-Request-Proxy-Retries").orElse("0");
System.out.println("Completed after " + retries + " retries");

import Network.HTTP.Simple

main :: IO ()
main = do
  let request = setRequestHeader "Request-Proxy-Key" ["al_live_abc123"]
              $ setRequestHeader "Request-Proxy-Host" ["api.example.com"]
              $ setRequestHeader "Request-Proxy-Max-Retries" ["5"]
              $ setRequestHeader "Request-Proxy-Retry-Backoff" ["exponential"]
              $ setRequestHeader "Request-Proxy-Timeout" ["60000"]
              $ "GET https://api.requestproxy.com/v1/users"

  response <- httpBS request
  let retries = getResponseHeader "X-Request-Proxy-Retries" response
  putStrLn $ "Completed after " ++ show retries ++ " retries"

Circuit Breaker

Request Proxy protects your systems by detecting repeated failures to a target host and temporarily blocking requests until the host recovers.

  • Closed (normal): Requests pass through normally.
  • Open (blocking): After reaching the failure threshold, the circuit opens and blocks all requests with a 503 error.
  • HalfOpen (testing): After the reset timeout, a single test request is allowed. If successful, the circuit closes. If it fails, the circuit reopens.

Response Headers

HeaderDescription
X-Request-Proxy-Circuit-StateCurrent circuit state: Closed, Open, or HalfOpen

Error Responses

StatusErrorDescription
503Circuit breaker openTarget API is failing repeatedly, try again later

Code Examples

# Check circuit breaker state in response headers
curl -X GET "https://api.requestproxy.com/v1/users" \
  -H "Request-Proxy-Key: al_live_abc123" \
  -H "Request-Proxy-Host: api.example.com" \
  -v  # Verbose mode to see response headers

# Handle 503 Circuit Breaker Open error
# X-Request-Proxy-Circuit-State: Open
# Retry after the reset timeout (typically 60 seconds)

import requests
import time

response = requests.get(
    "https://api.requestproxy.com/v1/users",
    headers={
        "Request-Proxy-Key": "al_live_abc123",
        "Request-Proxy-Host": "api.example.com",
    }
)

circuit_state = response.headers.get("X-Request-Proxy-Circuit-State")
print(f"Circuit state: {circuit_state}")

if response.status_code == 503:
    print("Circuit breaker is open. Retrying after 60 seconds...")
    time.sleep(60)
    # Retry request

const response = await fetch("https://api.requestproxy.com/v1/users", {
  headers: {
    "Request-Proxy-Key": "al_live_abc123",
    "Request-Proxy-Host": "api.example.com",
  },
});

const circuitState = response.headers.get("X-Request-Proxy-Circuit-State");
console.log(`Circuit state: ${circuitState}`);

if (response.status === 503) {
  console.log("Circuit breaker is open. Retrying after 60 seconds...");
  await new Promise(resolve => setTimeout(resolve, 60000));
  // Retry request
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.requestproxy.com/v1/users"))
    .header("Request-Proxy-Key", "al_live_abc123")
    .header("Request-Proxy-Host", "api.example.com")
    .GET()
    .build();

HttpResponse<String> response = client.send(
    request, HttpResponse.BodyHandlers.ofString());

String circuitState = response.headers()
    .firstValue("X-Request-Proxy-Circuit-State").orElse("Unknown");
System.out.println("Circuit state: " + circuitState);

if (response.statusCode() == 503) {
    System.out.println("Circuit breaker is open. Retrying after 60 seconds...");
    Thread.sleep(60000);
    // Retry request
}

import Network.HTTP.Simple
import Control.Concurrent (threadDelay)

main :: IO ()
main = do
  let request = setRequestHeader "Request-Proxy-Key" ["al_live_abc123"]
              $ setRequestHeader "Request-Proxy-Host" ["api.example.com"]
              $ "GET https://api.requestproxy.com/v1/users"

  response <- httpBS request
  let circuitState = getResponseHeader "X-Request-Proxy-Circuit-State" response
  putStrLn $ "Circuit state: " ++ show circuitState

  when (getResponseStatusCode response == 503) $ do
    putStrLn "Circuit breaker is open. Retrying after 60 seconds..."
    threadDelay 60000000  -- 60 seconds in microseconds
    -- Retry request

Concurrency Limits

Request Proxy limits the number of simultaneous in-flight requests per account to protect backend services from overload.

  • Configuration: Set via MAX_CONCURRENT_REQUESTS environment variable. Disabled when not configured.
  • Scope: Per account, across all API keys
  • Release: Slots are released immediately when a request completes (success or failure)

Response Headers

HeaderDescription
X-Request-Proxy-Request-IdUnique identifier for the request

Error Responses

StatusErrorDescription
429Concurrency limit exceededToo many simultaneous requests, wait for one to complete

Code Examples

# Make a request and check for concurrency limit errors
curl -s -w '\n%{http_code}' \
  -X GET "https://api.requestproxy.com/v1/users" \
  -H "Request-Proxy-Key: al_live_abc123" \
  -H "Request-Proxy-Host: api.example.com"

# If you receive a 429 with error_type "concurrency_limit_exceeded",
# wait briefly and retry:
# sleep 1 && curl ...

import requests
import time

response = requests.get(
    "https://api.requestproxy.com/v1/users",
    headers={
        "Request-Proxy-Key": "al_live_abc123",
        "Request-Proxy-Host": "api.example.com",
    }
)

if response.status_code == 429:
    error = response.json()
    if error.get("error_type") == "concurrency_limit_exceeded":
        print("Concurrency limit hit. Retrying after delay...")
        time.sleep(1)
        # Retry request
else:
    print(response.json())

const response = await fetch("https://api.requestproxy.com/v1/users", {
  headers: {
    "Request-Proxy-Key": "al_live_abc123",
    "Request-Proxy-Host": "api.example.com",
  },
});

if (response.status === 429) {
  const error = await response.json();
  if (error.error_type === "concurrency_limit_exceeded") {
    console.log("Concurrency limit hit. Retrying after delay...");
    await new Promise(resolve => setTimeout(resolve, 1000));
    // Retry request
  }
} else {
  const data = await response.json();
  console.log(data);
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.requestproxy.com/v1/users"))
    .header("Request-Proxy-Key", "al_live_abc123")
    .header("Request-Proxy-Host", "api.example.com")
    .GET()
    .build();

HttpResponse<String> response = client.send(
    request, HttpResponse.BodyHandlers.ofString());

if (response.statusCode() == 429) {
    System.out.println("Concurrency limit hit. Retrying after delay...");
    Thread.sleep(1000);
    // Retry request
}

import Network.HTTP.Simple
import Control.Concurrent (threadDelay)

main :: IO ()
main = do
  let request = setRequestHeader "Request-Proxy-Key" ["al_live_abc123"]
              $ setRequestHeader "Request-Proxy-Host" ["api.example.com"]
              $ "GET https://api.requestproxy.com/v1/users"

  response <- httpBS request
  if getResponseStatusCode response == 429
    then do
      putStrLn "Concurrency limit hit. Retrying after delay..."
      threadDelay 1000000  -- 1 second in microseconds
      -- Retry request
    else print (getResponseBody response)

Ready to get started?

Create Your API Key