Buffers

A Buffer is an ordered stream that delivers your requests to one endpoint at a rate you set — in submission order, with automatic retries, no infrastructure to manage. Define the target once, push items in, and Fliq releases them at your configured rate so you stay under the limit.

When to use buffers

Use buffers when you need to send many requests to the same endpoint without overwhelming it. Common use cases:

• Draining a webhook backlog to a third-party API with rate limits
• Fanning out notifications to a single downstream service
• Batch-processing event payloads at a controlled pace

Creating a buffer

A buffer stores the target URL, HTTP method, default headers, and rate limit. Every item pushed into the buffer inherits this configuration.

Fields

{
  "name":            string,   // required — unique per user (max 256 chars)
  "url":             string,   // required — the endpoint Fliq will call
  "method":          string,   // optional — GET | POST | PUT | PATCH | DELETE (default: POST)
  "headers":         object,   // optional — default headers for all items
  "timeout_seconds": number,   // optional — 1–3600 (default: 30)
  "rate_limit":      number,   // optional — max requests per second, 1–1000 (default: 10)
  "max_retries":     number,   // optional — 0–20 (default: 3)
  "backoff":         string,   // optional — "exponential" | "linear" (default: "exponential")
  "webhook_url":     string,   // optional — notified on item completion/failure
  "webhook_headers": object    // optional — headers for webhook calls
}

Example

curl -X POST https://api.fliq.sh/buffers \
  -H "Authorization: Bearer fliq_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "stripe-webhooks",
    "url": "https://api.example.com/webhooks/stripe",
    "method": "POST",
    "headers": { "Authorization": "Bearer sk_live_..." },
    "rate_limit": 5,
    "max_retries": 3,
    "backoff": "exponential"
  }'

Pushing items

Each item represents a single HTTP request to be sent. Items inherit the buffer's URL, method, and headers — you only need to provide the body and any header overrides.

Fields

{
  "body":    string,   // optional — request body
  "headers": object    // optional — merged with buffer defaults (item wins on conflict)
}

Example

curl -X POST https://api.fliq.sh/buffers/BUFFER_ID/items \
  -H "Authorization: Bearer fliq_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "body": "{\"event\": \"payment.completed\", \"amount\": 4999}",
    "headers": { "X-Idempotency-Key": "pay_abc123" }
  }'

How delivery works

Each buffer is a per-second token bucket. Fliq refills up to rate_limit tokens every second and spends one token per request, so your target endpoint never receives more than rate_limit requests per second — no bursts, no 429s.

Items are delivered one at a time, in submission order: at most one request per buffer is in flight at any moment. If an item fails it retries in place, holding its spot — a later item never overtakes an earlier one until that earlier one either succeeds or exhausts its retries.

Item lifecycle

• pending — waiting its turn to be delivered
• running — HTTP request in flight
• completed — endpoint returned 2xx
• failed — all retries exhausted without a 2xx

Rate limit handling (429)

If the target endpoint returns 429 Too Many Requests, Fliq reschedules the item using the Retry-After header (default: 60 seconds). This does not count as a retry attempt — the item keeps its full retry budget.

Retries and backoff

Non-2xx responses (other than 429) consume a retry. The delay before the next attempt depends on the backoff strategy:

• Exponential (default) — 30s × 2^attempt, capped at 1 hour, with ±25% jitter
• Linear— 30s × (attempt + 1)

Pause and resume

You can pause a buffer to temporarily stop delivery without losing pending items. New items can still be pushed while paused — they are delivered when you resume.

# Pause
curl -X POST https://api.fliq.sh/buffers/BUFFER_ID/pause \
  -H "Authorization: Bearer fliq_sk_..."

# Resume
curl -X POST https://api.fliq.sh/buffers/BUFFER_ID/resume \
  -H "Authorization: Bearer fliq_sk_..."

Monitoring items

List items to check their status, or fetch a single item for details including the HTTP status code and any error message.

# List all items (supports ?status=pending&limit=20&cursor=...)
curl https://api.fliq.sh/buffers/BUFFER_ID/items \
  -H "Authorization: Bearer fliq_sk_..."

# Get a single item
curl https://api.fliq.sh/buffers/BUFFER_ID/items/ITEM_ID \
  -H "Authorization: Bearer fliq_sk_..."

Crash recovery

If a worker crashes mid-execution, the item's heartbeat stops updating. A background reaper detects stale items within 30 seconds and either reschedules them (if retries remain) or marks them as failed. No manual intervention needed.