Pagination, errors and limits

How the Duun API paginates lists, reports errors, applies rate limits and makes retries safe with idempotency keys.

On this page

These rules apply to every endpoint. Build them into your client once and the rest of the API behaves predictably. The official SDKs already handle all of it.

Pagination

List endpoints (GET /runs, GET /factories, GET /skills and so on) use cursor pagination. Results come newest first unless an endpoint says otherwise.

Query parameterDescription
limitHow many objects to return, 1–100. Default 20.
cursorThe next_cursor from the previous page. Omit it for the first page.

Every list response has the same shape:

{
  "object": "list",
  "data": [{ "id": "run_7f3aK2pQ", "object": "run" }],
  "has_more": true,
  "next_cursor": "cur_Q2hyaXMtMjAyNi0xMS0xNQ"
}

When has_more is false, next_cursor is null and you have everything. Cursors are opaque: don’t parse or build them, and don’t reuse one with different filters. A cursor stays valid for 24 hours.

# First page
curl "https://api.duun.ai/v1/runs?factory_id=fac_platform&limit=100" \
  -H "Authorization: Bearer $DUUN_API_KEY"

# Next page: pass next_cursor back with the same filters
curl "https://api.duun.ai/v1/runs?factory_id=fac_platform&limit=100&cursor=cur_Q2hyaXMtMjAyNi0xMS0xNQ" \
  -H "Authorization: Bearer $DUUN_API_KEY"
import Duun from "@duun/sdk";

const duun = new Duun({ apiKey: process.env.DUUN_API_KEY });

// List methods return async iterables that fetch the next page as you go.
for await (const run of duun.runs.list({ factory_id: "fac_platform", limit: 100 })) {
  console.log(run.id, run.status);
}

// Or work page by page.
let page = await duun.runs.list({ factory_id: "fac_platform", limit: 100 });
while (page) {
  console.log(page.data.length);
  page = page.has_more ? await page.nextPage() : null;
}
from duun import Duun

client = Duun()

# Iterating a list fetches the next page as you go.
for run in client.runs.list(factory_id="fac_platform", limit=100):
    print(run.id, run.status)

# Or work page by page.
page = client.runs.list(factory_id="fac_platform", limit=100)
while page:
    print(len(page.data))
    page = page.next_page() if page.has_more else None

Errors

Duun uses standard HTTP status codes. 2xx means success, 4xx means something about the request needs fixing, and 5xx means something went wrong on our side. Every error response has the same body:

Error
{
  "error": {
    "type": "invalid_request",
    "code": "parameter_invalid",
    "message": "limit must be between 1 and 100.",
    "param": "limit",
    "request_id": "req_8Kc2Vd91TfQx"
  }
}
FieldDescription
typeThe category of error. One of the types below. Branch on this.
codeA more specific, stable reason, such as parameter_invalid, missing_scope or run_not_cancellable. New codes can appear at any time.
messageA human-readable explanation. Show it in logs; don’t parse it.
paramThe parameter at fault, when there is one. Otherwise null.
request_idThe same value as the Duun-Request-Id header.

Error types

TypeStatusWhat it meansWhat to do
invalid_request400The request is malformed: a missing or invalid parameter, bad JSON, or an unknown field.Fix the request. Don’t retry it unchanged.
authentication_error401The API key is missing, malformed, revoked or expired.Check the Authorization header and the key in Settings → API keys & secrets.
permission_denied403The key is valid but can’t do this: a missing scope, a built-in object, or a plan that doesn’t include the feature.Check code. Add the scope or use a different key.
not_found404The object doesn’t exist, or the key can’t see it.Check the id. Objects in other workspaces always return 404.
conflict409The request conflicts with the object’s current state, for example applying a workflow version on top of a stale revision or cancelling a finished run.Fetch the object again, reconcile, and retry.
idempotency_error409The Idempotency-Key was already used with a different request body, or the first request with that key is still in progress.Use a new key for a new request. Retry the same body with the same key.
validation_error422The request is well formed but the content isn’t valid, such as a workflow with problems.Read problems and fix each one.
rate_limited429Too many requests for this key.Wait for Retry-After seconds, then retry.
api_error500Something went wrong on our side.Retry with backoff and the same idempotency key.
service_unavailable503Duun is temporarily unavailable or under maintenance.Retry with backoff. Check status.duun.ai.

validation_error responses add a problems array. For workflows, each problem names the step and field, with the same message you’d see in the editor:

Validation error
{
  "error": {
    "type": "validation_error",
    "code": "workflow_invalid",
    "message": "The workflow has 2 problems to fix.",
    "param": "config",
    "request_id": "req_3nWq0LmZr7Ab",
    "problems": [
      {
        "step_id": "size",
        "field": "otherwise",
        "message": "Every condition needs an otherwise — pick at least one fallback stage.",
        "severity": "error"
      },
      {
        "step_id": "post-result",
        "field": "channel",
        "message": "Choose a channel.",
        "severity": "error"
      }
    ]
  }
}

Only severity: "error" problems block a request. Warnings are returned for information, for example from POST /workflows/{workflow_id}/diff.

Handling errors well

  • Branch on type, then on code if you need to. Never on message.
  • Retry only rate_limited, api_error, service_unavailable, and network failures where you got no response. Retrying a 4xx with the same body gives the same answer.
  • Send an Idempotency-Key on every POST, so a retry after a timeout can’t start a second run.
  • Log request_id with every failure.

Rate limits

During the preview each API key gets, by default:

KindLimit
Reads (GET)600 requests per minute
Writes (POST, PATCH, DELETE)120 requests per minute

These defaults may change before general availability. If you need more, contact support with your use case.

Every response tells you where you stand:

HeaderDescription
RateLimit-LimitRequests allowed in the current window for this kind of request
RateLimit-RemainingRequests left in the current window
RateLimit-ResetSeconds until the window resets
Retry-AfterOn 429 only: seconds to wait before retrying

Following run logs with follow=true holds one connection open and counts as a single read. Prefer it, or a webhook endpoint, to polling GET /runs/{run_id} in a tight loop.

Retrying with backoff

When you get a 429, wait at least Retry-After seconds. For 5xx responses and network errors, back off exponentially with jitter and give up after a few attempts. The SDKs do this for you (maxRetries defaults to 2).

# curl can retry 429 and 5xx responses, honouring Retry-After.
curl https://api.duun.ai/v1/runs \
  --retry 3 --retry-all-errors --retry-max-time 60 \
  -H "Authorization: Bearer $DUUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"factory_id": "fac_platform", "prompt": "Bump node to 22.11 in CI images"}'
async function withBackoff<T>(call: () => Promise<Response>, attempts = 4): Promise<T> {
  for (let i = 0; ; i++) {
    const res = await call();
    if (res.ok) return res.json() as Promise<T>;
    const retryable = res.status === 429 || res.status >= 500;
    if (!retryable || i === attempts - 1) throw new Error(`Duun API ${res.status}: ${await res.text()}`);
    const retryAfter = Number(res.headers.get("Retry-After"));
    const backoff = Math.min(2 ** i * 500, 8000) * (0.5 + Math.random());
    await new Promise((r) => setTimeout(r, retryAfter ? retryAfter * 1000 : backoff));
  }
}

// Reuse the same idempotency key on every attempt.
const key = crypto.randomUUID();
const run = await withBackoff(() =>
  fetch("https://api.duun.ai/v1/runs", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.DUUN_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": key,
    },
    body: JSON.stringify({ factory_id: "fac_platform", prompt: "Bump node to 22.11 in CI images" }),
  }),
);
import os, random, time, uuid
import httpx

def with_backoff(send, attempts=4):
    for i in range(attempts):
        res = send()
        if res.is_success:
            return res.json()
        retryable = res.status_code == 429 or res.status_code >= 500
        if not retryable or i == attempts - 1:
            res.raise_for_status()
        retry_after = res.headers.get("Retry-After")
        delay = float(retry_after) if retry_after else min(2**i * 0.5, 8) * (0.5 + random.random())
        time.sleep(delay)

key = str(uuid.uuid4())  # reuse on every attempt
run = with_backoff(lambda: httpx.post(
    "https://api.duun.ai/v1/runs",
    headers={"Authorization": f"Bearer {os.environ['DUUN_API_KEY']}", "Idempotency-Key": key},
    json={"factory_id": "fac_platform", "prompt": "Bump node to 22.11 in CI images"},
))

Idempotency

Network failures happen. If a POST /runs times out, you can’t tell whether the run started. Idempotency keys make the retry safe: send the same Idempotency-Key header with the same body, and Duun returns the original result instead of doing the work twice.

  • Send Idempotency-Key on every POST. Any unique string up to 255 characters works; a UUID v4 is a good choice.
  • Duun keeps the result for each key for 24 hours, per API key.
  • A retry with the same key and the same body returns the stored status code and body, with the header Idempotent-Replayed: true.
  • A request with a key that was already used with a different body fails with 409 idempotency_error. Generate a new key for each new operation.
  • If the first request with a key is still being processed, a concurrent retry also gets 409 idempotency_error with code request_in_progress. Wait a moment and retry.
  • Errors from validation (400, 422) aren’t stored, so you can fix the body and retry with the same key. Server errors (500) are stored only if the operation partly happened.
  • GET, PATCH and DELETE are naturally idempotent and ignore the header.
curl https://api.duun.ai/v1/runs \
  -H "Authorization: Bearer $DUUN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1b8c2e-5d4a-4f6e-9b7c-2a1d0e9f8c7b" \
  -d '{"factory_id": "fac_platform", "issue_url": "https://linear.app/acme/issue/PLT-482"}'
// The SDK generates a key per call and reuses it on its own retries.
// Pass your own when the retry happens outside the SDK, e.g. a re-queued job.
const run = await duun.runs.create(
  { factory_id: "fac_platform", issue_url: "https://linear.app/acme/issue/PLT-482" },
  { idempotencyKey: `plt-482-${job.id}` },
);
run = client.runs.create(
    factory_id="fac_platform",
    issue_url="https://linear.app/acme/issue/PLT-482",
    idempotency_key=f"plt-482-{job.id}",
)
Replayed response headers
HTTP/1.1 201 Created
Duun-Request-Id: req_8Kc2Vd91TfQx
Duun-Version: 2026-11-01
Idempotent-Replayed: true

    Type to search the docs, help center and blog.