Errors & limits

The shared error model, idempotency, rate limits, polling conventions, and data region notes.

Every Migration API endpoint shares one error model, one idempotency model, and one rate limit.

Status codes

Status	Meaning
400	Malformed request — a required field is missing or a value is invalid (e.g. an unknown template slug, a bad external_id, an invalid run kind).
401	API key missing, malformed, or revoked.
403	The account has no active plan. Only on endpoints that create work — see Plans.
404	The referenced migration, run, source, or template isn’t in your account.
409	A conflict — a reused external_id, an ambiguous source name, a run already in progress, or a state precondition (e.g. asking for the session log before the migration settles).
410	The resource expired and its data was deleted — an export job past its retention window. Start a new one.
412	A guarded write lost a race. Only from knowledge writes sent with if_unmodified_since — re-read, merge, and write again.
429	A rate limit or the concurrent-run limit. Check Retry-After.
500	Server error — safe to retry idempotent requests.
502	An upstream worker couldn’t be reached — document parsing or the export executor. Retry.
503	The feature isn’t available in your account’s data region.

Run-level failures are different from request errors: a POST /runs request can return 201 (accepted) and then resolve to a failed run. Read the run’s error field for the reason. See Poll a run.

Error body

Every error response is a JSON object with a single human-readable error string:

{ "error": "external_id must be alphanumeric (hyphens/underscores allowed), max 255 chars" }

Most errors carry only that string: there’s no field pointer or request-id header today, so branch on the HTTP status and surface error for debugging. The one exception is the concurrent-run limit, which adds a machine-readable code of run_concurrency_limit alongside the runs that triggered it.

Rate limits

Limits are counted per account, not per API key or per IP — keys belonging to the same account share one budget, and using a key from several machines doesn’t multiply it.

Each endpoint belongs to one of four classes, sized to what it costs us to serve:

Class	Limit	Endpoints
Reads	30 / minute	Polling a run, the preview, the session log, the thread, listing files, export job status and downloads, listing and reading sources and templates
Writes	10 / minute	Knowledge, pinning a source, source connections, editing a template or source, requesting upload URLs
Jobs	5 / hour	Starting an export
Agent	5 / hour	Starting a run, answering questions, submitting credentials

Two actions are capped more tightly still, because each one provisions something new:

Action	Limit
POST /migrations	1 per hour
POST /migrations/{id}/runs with kind: "generate"	1 per hour

Starting a run with kind of update, clarify or execute is not capped at one per hour — those continue a run you’ve already started rather than beginning new work — but they do count against the Agent class above.

The read budget assumes the documented polling cadence of ~10 seconds across up to 3 concurrent runs, which is 18 requests per minute, leaving room for previews and logs. If you poll faster you will hit the limit without learning anything sooner — use the thread stream for live progress instead.

There is an additional per-IP ceiling that absorbs bursts before authentication. It is deliberately not published: it sits well above these per-account limits and you will not meet it through normal use.

Over any limit you get a 429:

{ "error": "Too many requests" }

429 responses carry headers you should prefer over guessing:

Header	Meaning
Retry-After	Seconds until the window resets. Wait this long.
X-RateLimit-Limit	The limit for this bucket.
X-RateLimit-Remaining	Requests left in the current window.
X-RateLimit-Reset	Unix timestamp (seconds) when the window resets.

Space your run polling out so a fleet of concurrent migrations doesn’t burn the read budget on status checks — or switch to the thread stream, which doesn’t spend a read per update.

Concurrent runs

An account may have at most 3 runs in progress at a time, across every migration. This is separate from the per-migration rule — one run at a time per migration — and applies on top of it.

Only runs that are actually working count: queued, running, and blocked (waiting on your answer). A run sitting in awaiting_approval is waiting on you, not consuming capacity, so it doesn’t count against the limit.

Exceeding it returns 429 with a machine-readable code and the runs responsible:

{
  "error": "You already have 3 imports running, which is the limit. Wait for one to finish, or stop one to start another.",
  "code": "run_concurrency_limit",
  "limit": 3,
  "runs": [
    { "id": "run_...", "status": "running", "updatedAt": "2026-10-01T09:14:22.000Z", "runKind": "generate" }
  ]
}

Wait for one to finish, or cancel one, then retry.

File limits

A migration run is bounded by how many files it consumes, not by how many you upload over its lifetime:

Limit	Value
PDF and Word files per run	5
Files of any kind per run	400
Files per upload request	25

Only PDF and Word documents count toward the first limit — they go through document parsing, which is the expensive path. Spreadsheets and CSVs (.xlsx, .xls, .csv) do not count toward it, only toward the 400.

The per-request limit applies to a single POST /migrations/{id}/files call. It is not a ceiling on the migration — request URLs in batches of 25 and upload as many times as you need, up to the 400 total.

Over any of these you get a 400 naming which limit was hit and what the run would have totalled.

Plans

The endpoints that create work — POST /migrations, starting a run and starting an export — require an active subscription, and return 403 without one:

{ "error": "Your plan does not include data imports. Upgrade your plan to import data." }

Reads are unaffected, so an account between plans can still retrieve what it already has.

Idempotency

Migration creation is idempotent on the external_id you choose. Re-sending POST /migrations with the same external_id (and the same source) returns the existing migration — with a 200 instead of a 201 — rather than creating a second one. This makes create retries safe and doubles as recovery: if you lose a migration ID, re-POST with the same external_id to get it back.

Runs are not keyed by an idempotency token. Instead, only one run runs at a time per migration — starting a second while one is in flight returns 409 with the active run_id, which is how you recover a run you lost track of. See Start a run. Across migrations, an account is also capped at 3 runs in progress.

Polling conventions

• Poll runs on an interval of ≈2s, backing off as the run ages.
• Treat awaiting_approval, completed, failed, and canceled as terminal for a given run; stop polling.
• Make your handling idempotent — the same terminal state can be read more than once.
• Prefer the thread stream (SSE) over tight polling when you want live progress.

Data region

Migrations are created in your account’s region. If you need data to land in a specific region for residency reasons, talk to us at [e-mail] — additional regions are enabled per account.

Next

• Poll a run
• Start a run