Limits and errors

Task and request limits

The API also applies request throttling: 10 enrichment-task creations per 60-second window, and 120 requests per window for each other enrichment operation, per account. A throttled request returns 429 RateLimitExceeded with Retry-After in seconds. This is separate from the active-task limit below.

Limit	Value	Applies to
Inputs per creation request	1–10,000	Enrichment tasks only; sources have no inputs
Complete JSON request	10 MiB (10,485,760 bytes)	Both task families, including settings and inputs
Each input's data object	16 KiB (16,384 bytes)	Enrichment inputs, measured as compact UTF-8 JSON
Active tasks per account	Target of 20	Shared across enrichment and source tasks
Execution deadline	24 hours from creation	Both task families
Retention	90 days after completion, failure, or a stop	Task metadata, inputs, and results
List page size (limit)	1–100; default 50	Task history, inputs, and results
Result response page	128 KiB (131,072 bytes)	Both task families; may contain fewer rows than requested
JSON nesting depth	10 levels	Settings and input data

The account target is 20 active API tasks, counting queued, running, and stop_asked tasks whose deadlines have not passed. For example, 12 enrichment tasks leave room for 8 source tasks. Using a second API key does not give you more slots.

Simultaneous requests can occasionally exceed this target. This limit does not count runs started from the web app.

At the active-task limit, creation returns 429 ActiveTaskLimitExceeded. Wait for an existing task to become completed, failed, or stopped before creating another. Asking it to stop does not immediately free its slot. Honor Retry-After when present.

Submission size and execution batches

Send up to 10,000 inputs in one request, within the 10 MiB request limit. Datablist handles processing batches for you; the request uses one active-task slot.

For more than 10,000 inputs, or a request larger than 10 MiB, split your data into separate task creation requests. Give each task its own uniqueId and keep each input's inputId to match results to your records. Check the catalog's limits object for the current limits.

Identifiers and JSON values

inputId must be unique within a task, contain no control characters, and be at most 128 UTF-8 bytes. uniqueId is required: 1–128 ASCII letters, digits, underscores, or hyphens. Active duplicate checks are shared across both families.

Settings and input data must contain valid JSON. Integers must fit the signed 64-bit range; arrays cannot directly contain arrays. Object keys are at most 1,500 UTF-8 bytes and cannot use reserved __name__-style names. Customer keys such as data.id are preserved. Declared settings are validated against the tool's schema; additional settings still follow these JSON and request limits.

Follow every non-null nextCursor until it is null. The result byte limit can produce a short page even when more results are available.

HTTP errors

An error response tells you what failed in code and description. trace_id is an optional support reference. See the API statuses, codes, and headers.

json

{
  "http_status": 422,
  "code": "InvalidApiTask",
  "description": "The request data is invalid.",
  "trace_id": null
}

Status	What to check
401	Your access token is missing, invalid, or expired.
403	Your account lacks permission.
404	The task is missing, expired, or belongs to another account or API family.
409	A task already uses your uniqueId, or results are not ready yet.
413	The request is too large.
422	Check the input, settings, or enrichment ID against the catalog.
429	Slow down requests or wait for active tasks to finish. Follow Retry-After when present.

API responses include X-Request-ID. Keep that value when reporting an unexpected problem to Datablist support. Failed task metadata can also include a traceId; routine failures may leave it null.

Task errors and support traces

Both task families always include error. It is null during active work and successful completion. A failed task exposes this shape; a stopped task can also retain a failure that occurred before cancellation:

json

{
  "reason": "worker_failed",
  "code": "WORKER_FAILED",
  "message": "The worker could not finish the task.",
  "traceId": "er-example-support-reference"
}

Share the task ID and any error.traceId with support. The trace can be null, for example when a deadline or credit limit caused the failure.

Use reason in application logic and message to explain the failure to a user. Reasons are dispatch_failed, deadline_exceeded, worker_failed, enrichment_failed, and credits_error.

An enrichment result can also contain its own error: {code, message} for that input. Inspect both the task error and per-input errors. Source results are flat objects, so source execution failures appear at task level.

HTTP request errors use trace_id in the envelope above; persisted task errors use traceId. Keep both references, plus X-Request-ID, when available.

Network errors and safe retries

For reads, retry temporary network failures or 502, 503, and 504 responses with increasing delays and a retry limit. Follow Retry-After when present.

Before retrying task creation, check history for your uniqueId: the first request may already have started paid work. See safe retries.

503 ApiTaskDispatchFailed means some work could not be started. The task is marked failed, but work already started may have consumed credits. Save any returned task ID and read its results before deciding to run it again.