Target Rate-Limiting Outbound Queues

The Target Rate-Limiting Outbound Queue System (Outbound Throttling Engine) is a gateway reliability module designed to protect target CMS, ERP, e-commerce (e.g., WooCommerce, Shopify, 1C ERP), and financial backends from crashing under sudden high-concurrency request spikes.

Instead of hammering downstream systems with hundreds of concurrent API calls, the gateway intercepts non-GET requests matching a target domain queue, immediately responds to the caller with 202 Accepted, and dispatches the queued requests downstream at a strictly controlled rate (RPS).

Plan Limits & Access Control

Queue availability and limits depend on your active subscription plan:

Subscription Plan	Allowed Active Queues	Queue Interception Behavior
Free	0	Queue creation blocked (`403 Forbidden`). Proxy queue interception is bypassed; requests run directly.
Developer	1	Up to 1 active target rate-limiting queue.
Business & Enterprise	Up to 5	Up to 5 active target rate-limiting queues.

Configuration Parameters

Clients can configure and manage target queues directly via the Dashboard UI.

Parameter	Type	Validation / Constraints	Description
`name`	String	1–100 chars	Human-readable queue label (e.g., `ERP Orders Queue`).
`target_domain`	String	Valid domain	Target host domain to match (e.g., `api.mysite.com`).
`max_rate_rps`	Integer	1 to 50 RPS	Maximum outbound dispatch rate limit per second.
`max_queue_size`	Integer	100 to 10,000	Maximum number of pending requests allowed in Redis buffer.
`message_ttl_seconds`	Integer	300s (5m) to 10,800s (3h)	Hold expiration TTL before unhandled jobs expire.
`notify_on_failure`	Boolean	`true` / `false`	Enable Dead-Letter Webhook notifications on drop/TTL/failure.
`webhook_url`	String	Valid HTTP/HTTPS URL	Callback listener URL for Dead-Letter Queue (DLQ) drop notifications.

Request Processing Lifecycle

[Client Request]
       │
       ▼
┌───────────────────────────────┐
│ Authentication & Plan Check   │
└──────────────┬────────────────┘
               │
       Is Paid Plan (Dev/Biz)?
          ├── No (Free) ───────► Bypass Queue (Direct Proxy Execution)
          └── Yes
               │
       Is Method != GET & Target Queue Active?
          ├── No (GET / Paused) ──► Bypass Queue (Direct Proxy Execution)
          └── Yes
               │
┌──────────────▼────────────────┐
│ Enqueue into Redis Buffer     │
│ Instant 202 Accepted (<2ms)   │
└──────────────┬────────────────┘
               │
               ▼
┌───────────────────────────────┐
│ Outbound Rate Limiter Worker  │ (Atomic Redis SetNX Lock Window = 1000ms / RPS)
└──────────────┬────────────────┘
               │
               ▼
┌───────────────────────────────┐
│ Downstream Proxy Execution    │ (Preserves X-Retry-Count, X-Proxy-Timeout, etc.)
└──────────────┬────────────────┘
               │
       ┌───────┴───────┐
       ▼               ▼
[200 OK Response]  [5xx / TTL Expiry]
       │               │
 Log Access Metric     Trigger Dead-Letter Webhook (if enabled)

Key Execution Rules

GET Requests: Always bypass target queues and run directly via the standard proxy pipeline.
Paused State (is_active = false): When paused, queue interception is bypassed and requests pass directly to downstream targets.
Resilience Preservation: Queued jobs retain all original resilience headers (X-Retry-Count, X-Proxy-Timeout, X-Smart-Cache, X-Failover-URL).
Dead-Letter Webhook: On queue overflow, TTL expiration, or upstream failure, a POST notification is sent to webhook_url if notify_on_failure is true.

Client Usage Examples

1. Enqueuing a High-Concurrency POST Request

Request:

curl --location 'https://proxy.mirapi.io/' \
  --header 'X-MirApi-Key: your_api_key_here' \
  --header 'X-Target-URL: https://api.mysite.com/v1/orders' \
  --header 'X-Retry-Count: 3' \
  --header 'X-Proxy-Timeout: 15s' \
  --header 'Content-Type: application/json' \
  --data '{
    "order_id": "ORD-99214",
    "customer": "John Doe",
    "amount": 149.99
  }'

Synchronous Response (< 2ms):

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "status": "queued",
  "job_id": "1c7f8499-66dc-4689-99ff-f74837afa5ee",
  "queue_id": "52f00232-78b0-465b-a6ec-5103459b8a16",
  "target_domain": "api.mysite.com",
  "message": "Request queued for rate-throttled outbound execution"
}

2. URL Query Parameter Fallback (Shopify / Third-Party Webhooks)

If your webhook producer does not allow configuring custom HTTP headers, pass the orchestration flags via URL query parameters:

curl --location 'https://proxy.mirapi.io/?apiKey=your_api_key_here&target=https://api.mysite.com/v1/orders&retry_count=3&timeout=15s' \
  --header 'Content-Type: application/json' \
  --data '{"order_id": "ORD-1002"}'

3. Dead-Letter Queue (DLQ) Notification Payload

When a queued job fails after retries or expires in queue (TTL), the gateway posts a notification to your configured webhook_url:

POST /webhooks/dlq HTTP/1.1
Host: mycrm.com
Content-Type: application/json

{
  "job_id": "1c7f8499-66dc-4689-99ff-f74837afa5ee",
  "queue_id": "52f00232-78b0-465b-a6ec-5103459b8a16",
  "user_id": "8a852528-d79d-4da5-8e12-89b9fbde8554",
  "target_url": "https://api.mysite.com/v1/orders",
  "target_domain": "api.mysite.com",
  "reason": "upstream_failure",
  "error_message": "upstream returned status code: 500",
  "created_at": "2026-08-02T21:08:35Z",
  "failed_at": "2026-08-02T21:08:37Z"
}