Errors and pagination

Error envelope

Every non-2xx response has the same shape:

{
  "error": "Invalid agent_id format"
}

The HTTP status code carries the class of failure; the error string is a human-readable hint. Don’t pattern-match on the message text; it’s free-form and may change. Branch on the status code instead.

Status code reference

Status	Meaning	What to do
`400 Bad Request`	Malformed request: invalid UUID, missing required field, oversized file.	Fix the request; do not retry as-is.
`401 Unauthorized`	API key missing, malformed, or revoked.	Mint a new key (see Authentication).
`403 Forbidden`	Key is valid but the agent/task lives in another workspace.	Use a key scoped to the right workspace.
`404 Not Found`	Agent or task UUID doesn’t exist.	Check the ID. Note: this is also returned for resources in other workspaces, so a stolen ID can’t be probed.
`409 Conflict`	State-conflict (e.g. publishing an agent that has no draft changes).	Inspect the message; the operation isn’t valid right now.
`429 Too Many Requests`	Rate limit hit.	Back off (see below).
`500 Internal Server Error`	Unexpected server-side error.	Safe to retry with exponential backoff.
`503 Service Unavailable`	Temporary outage / deploy.	Retry with backoff.

When to retry

Class	Retry?
`4xx` except `429`	No. The request itself is wrong; fix and re-send.
`429`	Yes, after a back-off. Respect any `Retry-After` header if present.
`5xx`	Yes, these are transient. Use exponential backoff (1s → 2s → 5s → 10s, cap at ~30s) with full jitter, and give up after 4–5 attempts.

A minimal retry helper:

Python

import os, time, random, requests

def with_retries(method, url, *, max_attempts=5, **kwargs):
    delay = 1.0
    for attempt in range(max_attempts):
        r = requests.request(method, url, **kwargs)
        if r.status_code < 500 and r.status_code != 429:
            return r
        if attempt == max_attempts - 1:
            r.raise_for_status()
        retry_after = r.headers.get("Retry-After")
        sleep = float(retry_after) if retry_after else min(delay, 30) * (1 + random.random())
        time.sleep(sleep)
        delay *= 2

A 5xx or a timeout on POST /v1/agents/{agent_id}/run can mean “the request reached us, then the connection died”, so a blind retry can start a second run. Send an Idempotency-Key header (a fresh UUID per run) and reuse it on every retry of that run: for 24 hours the same request under the same key returns the task the first one created, with Idempotent-Replayed: true, instead of starting another. A 409 means the first request is still creating its task; retry after Retry-After. A 422 means the key was already used with a different request.

Python

import os, uuid

key = str(uuid.uuid4())  # one key per run, reused on every retry of it
r = with_retries("POST", f"https://agents.nanonets.com/api/v1/agents/{agent_id}/run",
                 headers={"Authorization": f"Bearer {os.environ['NANONETS_API_KEY']}",
                          "Idempotency-Key": key},
                 json={"query": "Extract the invoice"})

Pagination

List endpoints (GET /v1/tasks, GET /v1/agents, GET /v1/agents/{id}/versions) are cursor-paginated, newest-first. The response looks like:

{
  "tasks": [ /* … up to `limit` items … */ ],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0xMlQwOToxNTowMFoiLCJpZCI6IjFhMmIzYy0..."
}

To fetch the next page, pass that cursor back unchanged as the cursor query parameter. When you reach the end, next_cursor is omitted (or empty).

# First page
curl "https://agents.nanonets.com/api/v1/tasks?limit=50" \
  -H "Authorization: Bearer $NANONETS_API_KEY"

# Subsequent page
curl "https://agents.nanonets.com/api/v1/tasks?limit=50&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $NANONETS_API_KEY"

Python

def iter_tasks(**filters):
    cursor = None
    while True:
        params = {"limit": 100, **filters}
        if cursor:
            params["cursor"] = cursor
        r = requests.get(f"{BASE}/api/v1/tasks", headers=HEADERS, params=params).json()
        for task in r["tasks"]:
            yield task
        cursor = r.get("next_cursor")
        if not cursor:
            return

for task in iter_tasks(agent_id="…", status="completed"):
    print(task["task_id"], task["title"])

Cursor opacity

next_cursor is opaque; don’t try to parse it. If you decode it today and rely on the shape, your code will break the next time the server changes its pagination key.

`limit`

Default is 20, max is 100. Larger pages mean fewer round-trips but a larger response body; for bulk export, 100 is usually the right choice.

Rate limits

Rate limits are enforced per-workspace, not per-key. If you’re running tight loops or fanning out many concurrent agents, watch for 429 and back off. We do not currently publish per-tier numbers. If you’re hitting limits in production, reach out.

Getting started

Build your agent

Teach your agent

Run tasks & get results

See how it is going

Collaborate

Manage your account

Working with the API

Error envelope

Status code reference

When to retry

Cursor opacity

`limit`

Rate limits

​Error envelope

​Status code reference

​When to retry

​Pagination

​Cursor opacity

​limit

​Rate limits

Error envelope

Status code reference

When to retry

Pagination

Cursor opacity

`limit`

Rate limits