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 parameter | Description |
|---|---|
limit | How many objects to return, 1–100. Default 20. |
cursor | The 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 NoneErrors
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": {
"type": "invalid_request",
"code": "parameter_invalid",
"message": "limit must be between 1 and 100.",
"param": "limit",
"request_id": "req_8Kc2Vd91TfQx"
}
}| Field | Description |
|---|---|
type | The category of error. One of the types below. Branch on this. |
code | A more specific, stable reason, such as parameter_invalid, missing_scope or run_not_cancellable. New codes can appear at any time. |
message | A human-readable explanation. Show it in logs; don’t parse it. |
param | The parameter at fault, when there is one. Otherwise null. |
request_id | The same value as the Duun-Request-Id header. |
Error types
| Type | Status | What it means | What to do |
|---|---|---|---|
invalid_request | 400 | The request is malformed: a missing or invalid parameter, bad JSON, or an unknown field. | Fix the request. Don’t retry it unchanged. |
authentication_error | 401 | The API key is missing, malformed, revoked or expired. | Check the Authorization header and the key in Settings → API keys & secrets. |
permission_denied | 403 | The 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_found | 404 | The object doesn’t exist, or the key can’t see it. | Check the id. Objects in other workspaces always return 404. |
conflict | 409 | The 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_error | 409 | The 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_error | 422 | The request is well formed but the content isn’t valid, such as a workflow with problems. | Read problems and fix each one. |
rate_limited | 429 | Too many requests for this key. | Wait for Retry-After seconds, then retry. |
api_error | 500 | Something went wrong on our side. | Retry with backoff and the same idempotency key. |
service_unavailable | 503 | Duun 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:
{
"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 oncodeif you need to. Never onmessage. - Retry only
rate_limited,api_error,service_unavailable, and network failures where you got no response. Retrying a4xxwith the same body gives the same answer. - Send an
Idempotency-Keyon everyPOST, so a retry after a timeout can’t start a second run. - Log
request_idwith every failure.
Rate limits
During the preview each API key gets, by default:
| Kind | Limit |
|---|---|
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:
| Header | Description |
|---|---|
RateLimit-Limit | Requests allowed in the current window for this kind of request |
RateLimit-Remaining | Requests left in the current window |
RateLimit-Reset | Seconds until the window resets |
Retry-After | On 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-Keyon everyPOST. 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_errorwith coderequest_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,PATCHandDELETEare 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}",
)HTTP/1.1 201 Created
Duun-Request-Id: req_8Kc2Vd91TfQx
Duun-Version: 2026-11-01
Idempotent-Replayed: true