Error handling

The Bundata API uses standard HTTP status codes and JSON error payloads. Handle them consistently: interpret the status and error code, retry when appropriate (with backoff), and surface actionable messages to users or logs. This page covers status codes, error shape, retries, and idempotency.

HTTP status codes

Code	Meaning	Action
200, 201	Success	Process response body.
400	Bad request	Fix request (invalid params, schema, or body). Do not retry same payload.
401	Unauthorized	Invalid or missing API key. Fix credentials. See Authentication.
403	Forbidden	Key valid but not allowed for this resource or action. Check scopes and workspace.
404	Not found	Resource (e.g. run, collection, schema) doesn’t exist. Check IDs and paths.
429	Too many requests	Rate limited. Retry after the delay indicated in headers. See Rate limits.
5xx	Server error	Transient; retry with backoff. If persistent, contact Support.

Error response body

On 4xx and 5xx, the body is typically JSON with at least:

code — Machine-readable error code. See Error codes.
message — Human-readable description.
details — Optional; extra context (e.g. field name, limit value).

Example:

{
  "code": "INVALID_SCHEMA",
  "message": "Schema validation failed for field 'effective_date'.",
  "details": { "field": "effective_date", "reason": "expected date format YYYY-MM-DD" }
}

Use code for programmatic handling (e.g. different behavior for RATE_LIMITED vs INVALID_SCHEMA).

Retries

Do retry — 429 (rate limit) and 5xx. Use exponential backoff (e.g. 1s, 2s, 4s) and a max number of retries. Respect Retry-After when present.
Don’t retry — 400, 401, 403, 404 with the same request. Fix the request or credentials first.
Idempotency — For mutation endpoints (e.g. start run), use idempotency keys when supported so duplicate requests don’t create duplicate work. See product docs for idempotency key headers and behavior.

Extraction and workflow runs

Run failed — The run resource or job status will indicate failure. Error details may be in the run result or step output. Use Error codes to map codes to messages and next steps.
Partial success — Batch runs may return per-document status. Process successes and retry or fix failures separately.

Logging and monitoring

Log request ID (if returned in headers) and error code so you can correlate with Bundata support and debug issues.
Monitor 4xx/5xx rates and alert on sustained 5xx or 429 spikes. See Rate limits and Webhooks for automation.

Next steps

Error codes — Full list of codes and meanings.
Rate limits — Throttling and retry-after.
Authentication — Fixing 401/403.