Error codes
Bundata returns machine-readable error codes in API and run error responses. Use them for programmatic handling, logging, and user-facing messages. This page is a reference for common codes and recommended actions.
Authentication and authorization
| Code | HTTP | Description | Action |
|---|
UNAUTHORIZED | 401 | Missing or invalid API key. | Check Authorization header and key value. See Authentication. |
FORBIDDEN | 403 | Key valid but not allowed for this resource or action. | Check workspace, scopes, and permissions. |
EXPIRED_CREDENTIAL | 401 | Credential (e.g. connector) expired. | Refresh or re-authorize the connector. |
Request validation
| Code | HTTP | Description | Action |
|---|
INVALID_REQUEST | 400 | Malformed or invalid request body or params. | Fix JSON, required fields, and types. |
INVALID_SCHEMA | 400 | Schema validation failed (e.g. unknown field type, invalid structure). | Fix schema definition. See Schema field reference. |
VALIDATION_ERROR | 400 | Field-level validation (e.g. date format, required field missing). | Check details for field and reason; fix input or schema. |
Resources
| Code | HTTP | Description | Action |
|---|
NOT_FOUND | 404 | Resource (run, collection, schema, connector) not found. | Verify ID and path; ensure resource exists in the workspace. |
CONFLICT | 409 | Conflict (e.g. duplicate idempotency key, version mismatch). | Change request or use a new idempotency key. |
Rate limits and capacity
| Code | HTTP | Description | Action |
|---|
RATE_LIMITED | 429 | Too many requests. | Retry after Retry-After; reduce concurrency. See Rate limits. |
QUOTA_EXCEEDED | 429 | Usage quota (e.g. pages per month) exceeded. | Upgrade plan or wait for quota reset. See Limits and quotas. |
Extraction and runs
| Code | HTTP / run | Description | Action |
|---|
EXTRACTION_FAILED | 5xx / run failed | Extraction step failed (e.g. unsupported file, parse error). | Check file type and format; see Supported file types. |
UNSUPPORTED_FILE_TYPE | 400 / run | File type not supported. | Use a supported type or skip. See Supported file types. |
FILE_TOO_LARGE | 400 | Document exceeds size limit. | Split or compress; see Limits and quotas. |
CONNECTOR_ERROR | 5xx / run | Source or destination connector failed (e.g. auth, network). | Check connector config and credentials; see Source and Destination connectors. |
Server and transient
| Code | HTTP | Description | Action |
|---|
INTERNAL_ERROR | 500 | Unexpected server error. | Retry with backoff; if persistent, contact Support. |
SERVICE_UNAVAILABLE | 503 | Temporary unavailability. | Retry with backoff. Check Status. |
Error response shape
Responses typically include:
- code — One of the codes above (or a product-specific extension).
- message — Human-readable description.
- details — Optional object with field-specific or context-specific info (e.g.
field, limit, run_id).
Use code for branching in code; use message and details for logs and user-facing text.
Next steps