Errors and Limits

Document AI uses standard HTTP status codes and the Shipwell error envelope.

Error response format

Copy

Copied

{
  "errors": [
    {
      "code": "processing_config_not_found",
      "detail": "processing config not found or disabled",
      "source": null
    }
  ]
}

code is a stable token intended for application logic.
detail is a human-readable explanation and can change.
source can identify the invalid body field, header, or query parameter.

Branch on errors[].code, not the text in detail.

HTTP status codes

Status	Meaning
`400`	The request cannot be accepted, such as a blocked file or invalid upload metadata.
`401`	Authentication is missing or invalid.
`403`	The resource is visible but the requested operation is not permitted.
`404`	The resource or selected configuration is not available to the authenticated company.
`409`	The request conflicts with an existing resource, such as a duplicate configuration name.
`413`	The resource is too large for the requested inline response format.
`422`	The request body or query parameters do not match the schema.
`429`	The request exceeded a rate limit.
`502` or `503`	A required processing or search capability is temporarily unavailable.

Access to another company's resource returns 404.

Upload acceptance and processing eligibility

Upload limits have two distinct effects:

Storage acceptance — if the file cannot be accepted, the request fails and no document is created for that file.
Processing eligibility — a file can be accepted and stored but skipped for processing.

Do not assume a successful upload means processing also started. Inspect:

documents[].latest_run
skipped[]
status
process_skip_reason

Retrieve current file limits

File type support and limits can vary by MIME type and account. Retrieve the current catalog:

Use GET /document-store/configs/upload-file-types.

Important response fields:

Field	Meaning
`extension`	Accepted filename extension.
`mime_type`	MIME type for this rule.
`storage_max_bytes`	Maximum size accepted for storage.
`pipeline_max_bytes`	Maximum size eligible for processing.
`pipeline_eligible`	Whether this file type can be processed.
`max_pdf_pages`	Maximum PDF pages eligible for processing, when present.
`enabled`	Whether the rule currently accepts the file type.

Validate both extension and MIME type in your client, but always treat the API response as authoritative.

Common upload errors

Code	Meaning	Suggested action
`tier1_extension_blocked`	The file extension is not accepted.	Use a supported file type from the upload catalog.
`tier1_executable_detected`	The file content appears executable.	Reject the file and do not retry it unchanged.
`tier1_size_exceeded:<mime>`	The file exceeds `storage_max_bytes`.	Reduce the file or use a supported format within the limit.
`invalid_filename`	The filename is unsafe or invalid.	Use a plain filename without paths, control characters, or traversal sequences.
`too_many_files`	A multipart request contains more than 20 files.	Split the upload into multiple requests.
`invalid_base64`	Base64 content cannot be decoded.	Encode the original bytes again and retry.
`size_mismatch`	A committed direct upload does not match the declared size.	Verify the uploaded bytes and commit metadata.
`invalid_object_key`	Commit metadata does not match the prepared upload.	Use the values returned when the upload URL was created.

Common processing skip reasons

Skip reasons appear in upload or processing responses and on the document:

Reason	Meaning	Suggested action
`unsupported_for_pipeline`	The file can be stored but not processed.	Store it without processing or convert it to a supported format.
`per_mime_size_exceeded:<mime>`	The file exceeds `pipeline_max_bytes`.	Reduce or split the file before processing.
`pdf_page_cap_exceeded:<n>`	The PDF exceeds its configured page limit.	Split the PDF into smaller documents.
`pdf_page_pixels_exceeded:<n>`	A PDF page is too large to process safely.	Re-export the page at a smaller physical size or resolution.
`image_pixel_cap_exceeded:<n>`	An image contains more pixels than the processing limit.	Resize or re-export the image.
`llm_token_budget_exceeded`	Extracted content exceeds the supported processing budget.	Split the document or reduce unnecessary content.

The suffix after : provides context and should not be treated as a separate code family.

Configuration errors

Code	Meaning	Suggested action
`processing_config_not_found`	The selected configuration is missing, disabled, or unavailable to your company.	Refresh the configuration list and select an enabled configuration.
`processing_config_name_exists`	Your company already has a configuration with that name.	Choose a unique name.
`platform_config_immutable`	A platform-managed configuration cannot be changed or deleted.	Create a custom configuration instead.
`unknown_field`	The request contains a field not accepted by the current contract.	Remove the field and validate against the current API schema.

Resource lookup errors

Common tokens include:

document_not_found
not_found
result_not_found
result_file_not_found
schema_not_found
result_slice_missing_for_page
too_large_for_inline

For result_slice_missing_for_page, retrieve the document outline and use the result_id whose page list contains the requested page.

Rate limits

A 429 response uses code rate_limited.

When rate limited:

Stop immediate retries.
Apply exponential backoff with jitter.
Reduce concurrent requests.
Batch supported operations, such as multi-file upload or processing multiple document identifiers.
Contact Shipwell if sustained production traffic requires a different limit.

Retry guidance

Retry:

429 after backing off
Temporary 502 and 503 responses
Network timeouts when your operation is safely idempotent

Do not automatically retry:

Validation errors
Blocked or executable files
Immutable platform configuration changes
Duplicate configuration names

An upload timeout can occur after the server accepted the request. Before repeating it, search your recent documents by known metadata such as filename, association, and creation window, or use an application-level idempotency strategy to avoid duplicate uploads.