Errors & rate limits

#Error shape

Every error response — regardless of status code — is:

{ "error": { "code": "not_found", "message": "Run not found", "details": null } }

code is a stable, machine-readable string (safe to switch on); message is a human-readable English sentence (interfaces translate by code, not by parsing message — see Data & providers for how the console/web apps localize); details is present only on a handful of error codes that carry structured extra data.

#Common codes

#Idempotency

POST /v1/runs, POST /v1/runs/:id/input, and POST /v1/runs/:id/approve accept an Idempotency-Key header (POST /v1/runs/:id/review does not, currently — see Human-in-the-loop). Send a fresh UUID per logical operation:

• Same key + same workspace + same request body, within 24 hours → the original response is replayed verbatim, side effects and all — safe to retry after a timeout or a dropped connection.
• Same key + a different request body → 409 idempotency_key_conflict. Treat this as a bug in the caller (reusing a key across two different operations), not something to retry.
• Same key, concurrently in flight → 409 idempotency_in_progress. Retry after a short delay once the first attempt has completed.

async function createRunOnce(body: unknown, idempotencyKey: string) {
  const res = await fetch("https://api.agentflowbind.com/v1/runs", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.AFB_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey, // generate once per logical run, reuse it across retries
    },
    body: JSON.stringify(body),
  });
  return res.json();
}

#Rate limits

A 429 always includes Retry-After (seconds) except the SSE stream cap, which is a hard concurrency limit rather than a time window — close an existing stream (or wait for one to reach a terminal run status) before opening another.