Proxy API
Synchronous API for real-time requests with immediate responses
Proxy API
The Proxy API allows you to make authenticated requests to target APIs through your configured proxies. Requests are processed synchronously with immediate responses.
Overview
Once a proxy has been configured, you can immediately start making API requests to endpoints defined by:
- The region in which the proxy is deployed
- The credential type being used
- The ID of the proxy
Endpoint Format
https://{region_specific_baseURL}/api/{proxyId}/{your_target_path}URL Components
- region_specific_baseURL: The regional endpoint (e.g.,
us-east-1.requestrocket.com) - proxyId: Your proxy's unique identifier
- your_target_path: The path on your target API
The exact Base URL for your proxy is provided in the proxy details after creation. Copy it from the dashboard (or Core API response) for use in your application.
Authentication
All proxy requests require authentication. The authentication method is determined by the proxy credential type configured for your proxy.
RequestRocket supports the following authentication methods:
API Key
Include your API key in the Authorization header (or Authorization query parameter).
curl -X GET "https://{Your_ProxyAPI_URL}/{target_path}" \
-H "Content-Type: application/json" \
-H "Authorization: {API_Key_Value}"Bearer Token
Use a bearer token in the Authorization header (or Authorization query parameter).
curl -X GET "https://{Your_ProxyAPI_URL}/{target_path}" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {Token}"Basic Auth
Use username and password with Basic Auth in the header (or Authorization query parameter).
curl -X GET "https://{Your_ProxyAPI_URL}/{target_path}" \
-H "Content-Type: application/json" \
-H "Authorization: Basic {Base64_Encoded_Username:Password}"JWT
Use a JWT token directly in the header (or Authorization query parameter).
curl -X GET "https://{Your_ProxyAPI_URL}/{target_path}" \
-H "Content-Type: application/json" \
-H "Authorization: {JWT_Token}"OAuth 2.0
OAuth 2.0 and 2.1 endpoints are currently under development and not yet supported for proxy credentials.
HTTP Methods
The Proxy API supports all standard HTTP methods:
- GET: Retrieve resources
- POST: Create resources
- PUT: Update/replace resources
- PATCH: Partially update resources
- DELETE: Remove resources
- OPTIONS: Get available methods
- HEAD: Get headers only
Request Examples
GET Request
const response = await fetch(
'https://us-east-1.requestrocket.com/api/abc123/users/42',
{
method: 'GET',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer your-proxy-token'
}
}
);
const data = await response.json();import requests
response = requests.get(
'https://us-east-1.requestrocket.com/api/abc123/users/42',
headers={
'Content-Type': 'application/json',
'Authorization': 'Bearer your-proxy-token'
}
)
data = response.json()package main
import (
"encoding/json"
"io"
"net/http"
)
func main() {
client := &http.Client{}
req, _ := http.NewRequest("GET", "https://us-east-1.requestrocket.com/api/abc123/users/42", nil)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer your-proxy-token")
resp, _ := client.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var data map[string]interface{}
json.Unmarshal(body, &data)
}import java.net.http.*;
import java.net.URI;
public class GetRequest {
public static void main(String[] args) throws Exception {
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://us-east-1.requestrocket.com/api/abc123/users/42"))
.header("Content-Type", "application/json")
.header("Authorization", "Bearer your-proxy-token")
.GET()
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X GET "https://us-east-1.requestrocket.com/api/abc123/users/42" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-proxy-token"POST Request
const response = await fetch(
'https://us-east-1.requestrocket.com/api/abc123/users',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer your-proxy-token'
},
body: JSON.stringify({
name: 'John Doe',
email: 'john@example.com'
})
}
);
const data = await response.json();import requests
response = requests.post(
'https://us-east-1.requestrocket.com/api/abc123/users',
headers={
'Content-Type': 'application/json',
'Authorization': 'Bearer your-proxy-token'
},
json={
'name': 'John Doe',
'email': 'john@example.com'
}
)
data = response.json()package main
import (
"bytes"
"encoding/json"
"io"
"net/http"
)
func main() {
requestBody, _ := json.Marshal(map[string]string{
"name": "John Doe",
"email": "john@example.com",
})
client := &http.Client{}
req, _ := http.NewRequest("POST", "https://us-east-1.requestrocket.com/api/abc123/users",
bytes.NewBuffer(requestBody))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer your-proxy-token")
resp, _ := client.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var data map[string]interface{}
json.Unmarshal(body, &data)
}import java.net.http.*;
import java.net.URI;
public class PostRequest {
public static void main(String[] args) throws Exception {
String json = "{\"name\": \"John Doe\", \"email\": \"john@example.com\"}";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://us-east-1.requestrocket.com/api/abc123/users"))
.header("Content-Type", "application/json")
.header("Authorization", "Bearer your-proxy-token")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X POST "https://us-east-1.requestrocket.com/api/abc123/users" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-proxy-token" \
-d '{
"name": "John Doe",
"email": "john@example.com"
}'Response Headers
RequestRocket appends two custom headers to all proxy responses:
requestrocket-proxy-code
Indicates the proxy authentication status:
proxy-access-granted: Proxy authentication successfulproxy-access-denied: Proxy authentication failed
requestrocket-proxy-message
Provides a human-readable description of the proxy code.
Understanding Responses
Successful Proxy Authentication
If a request successfully passes proxy credential validation (accepted by the gateway), you'll see proxy-access-granted in the response headers - even if the target system returns an error.
This confirms:
- ✅ You're using the correct proxy credential
- ✅ RequestRocket has successfully processed your request
- ✅ The request was forwarded to the target API
Failed Proxy Authentication
If you see proxy-access-denied, it means:
- ❌ Your proxy credential is invalid
- ❌ You're using the wrong proxyId in the URL
Error Response with proxy-access-granted
If you see proxy-access-granted but receive an error response, the issue is not the proxy credential. Check:
- Target URL: The target API endpoint might be incorrect
- Request Format: Your request might be malformed for the target API
- Target Credential: The credential used to authenticate with the target might be invalid
If you're receiving errors and RequestRocket headers are attached, you're seeing the actual response from the target system.
Internal Server Errors
There's one notable exception: a 500 error generated from RequestRocket when something has gone very wrong.
If you receive a 500 error without RequestRocket headers, contact our support team as soon as convenient.
Request Flow
Response Headers & Error Codes
RequestRocket adds custom headers to all responses to help you understand the request flow and troubleshoot issues:
requestrocket-proxy-code: Status of proxy authentication (proxy-access-granted,proxy-access-denied, etc.)requestrocket-proxy-message: Human-readable description of the proxy coderequestrocket-proxy-warning: Warning messages about account or request status
The requestrocket-proxy-code header is key to understanding where an issue occurred. If you see proxy-access-granted with an error response, the issue is with the target API, not the proxy authentication.
Quick Reference:
| Proxy Code | Status | Issue Location |
|---|---|---|
proxy-access-denied | 403 | Invalid proxy credential or proxyId |
proxy-access-granted | 200-299 | ✅ Success |
proxy-access-granted | 400-499 | Target API or authorization rules |
proxy-access-granted | 500-599 | Target API error |
billing-suspended | 402 | Account payment required |
response-too-large | 413 | Response exceeds 6MB limit |
View complete response headers documentation →
Query Parameters
Query parameters are passed through to the target API:
curl -X GET "https://us-east-1.requestrocket.com/api/abc123/users?page=1&limit=20" \
-H "Authorization: Bearer your-proxy-token"The target API will receive:
GET /users?page=1&limit=20Request Headers
Most headers are passed through to the target API. However:
Modified Headers
- Host: Set to the target API host
- Authorization: Replaced with target credential
Preserved Headers
- Content-Type
- Content-Length
- Accept
- User-Agent
- Custom headers (X-*, etc.)
Added Headers
requestrocket-proxy-coderequestrocket-proxy-messageX-Forwarded-For(your IP)
Rate Limiting
Rate limits are applied per proxy credential:
| Plan | Rate Limit |
|---|---|
| Basic | 100 requests/minute |
| Team | 1,000 requests/minute |
| Business | Custom |
When exceeded, you'll receive a 429 Too Many Requests response.
Timeouts
- Default Timeout: 30 seconds
- Maximum Timeout: 60 seconds
If the target API doesn't respond within the timeout period, you'll receive a 504 Gateway Timeout error.