{"componentChunkName":"component---src-templates-simple-markdown-js","path":"/docs/ai/document-ai/errors-and-limits/","matchPath":"","result":{"data":{"markdownRemark":{"html":"

Errors and Limits

\n

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

\n

Error response format

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

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

\n

HTTP status codes

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

Access to another company's resource returns 404.

\n

Upload acceptance and processing eligibility

\n

Upload limits have two distinct effects:

\n
    \n
  1. \nStorage acceptance\n — if the file cannot be accepted, the request fails and no document is created for that file.\n
    2. \n
  2. \nProcessing eligibility\n — a file can be accepted and stored but skipped for processing.\n
    3. \n
\n

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

\n\n

Retrieve current file limits

\n

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

\n

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

\n

Important response fields:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldMeaning
extensionAccepted filename extension.
mime_typeMIME type for this rule.
storage_max_bytesMaximum size accepted for storage.
pipeline_max_bytesMaximum size eligible for processing.
pipeline_eligibleWhether this file type can be processed.
max_pdf_pagesMaximum PDF pages eligible for processing, when present.
enabledWhether the rule currently accepts the file type.
\n

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

\n

Common upload errors

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CodeMeaningSuggested action
tier1_extension_blockedThe file extension is not accepted.Use a supported file type from the upload catalog.
tier1_executable_detectedThe 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_filenameThe filename is unsafe or invalid.Use a plain filename without paths, control characters, or traversal sequences.
too_many_filesA multipart request contains more than 20 files.Split the upload into multiple requests.
invalid_base64Base64 content cannot be decoded.Encode the original bytes again and retry.
size_mismatchA committed direct upload does not match the declared size.Verify the uploaded bytes and commit metadata.
invalid_object_keyCommit metadata does not match the prepared upload.Use the values returned when the upload URL was created.
\n

Common processing skip reasons

\n

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ReasonMeaningSuggested action
unsupported_for_pipelineThe 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_exceededExtracted content exceeds the supported processing budget.Split the document or reduce unnecessary content.
\n

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

\n

Configuration errors

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CodeMeaningSuggested action
processing_config_not_foundThe selected configuration is missing, disabled, or unavailable to your company.Refresh the configuration list and select an enabled configuration.
processing_config_name_existsYour company already has a configuration with that name.Choose a unique name.
platform_config_immutableA platform-managed configuration cannot be changed or deleted.Create a custom configuration instead.
unknown_fieldThe request contains a field not accepted by the current contract.Remove the field and validate against the current API schema.
\n

Resource lookup errors

\n

Common tokens include:

\n\n

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

\n

Rate limits

\n

A 429 response uses code rate_limited.

\n

When rate limited:

\n
    \n
  1. \nStop immediate retries.\n
    2. \n
  2. \nApply exponential backoff with jitter.\n
    3. \n
  3. \nReduce concurrent requests.\n
    4. \n
  4. \nBatch supported operations, such as multi-file upload or processing multiple document identifiers.\n
    5. \n
  5. \nContact Shipwell if sustained production traffic requires a different limit.\n
    6. \n
\n

Retry guidance

\n

Retry:

\n\n

Do not automatically retry:

\n\n

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.

","headings":[{"value":"Errors and Limits","depth":1},{"value":"Error response format","depth":2},{"value":"HTTP status codes","depth":2},{"value":"Upload acceptance and processing eligibility","depth":2},{"value":"Retrieve current file limits","depth":2},{"value":"Common upload errors","depth":2},{"value":"Common processing skip reasons","depth":2},{"value":"Configuration errors","depth":2},{"value":"Resource lookup errors","depth":2},{"value":"Rate limits","depth":2},{"value":"Retry guidance","depth":2}]},"contentItem":{"data":{"lastModified":"2026-07-17T16:00:10.000Z","enableToc":null,"disableLastModified":null,"tocMaxDepth":null,"requestLogin":false}},"siteConfig":{"enableToc":true,"disableLastModified":false,"tocMaxDepth":4}},"pageContext":{"matchPath":"","id":"2d0f08e2-e28f-5420-b895-d0147c0b9c39__redocly content/docs/ai/document-ai/errors-and-limits/","seo":{"title":"Errors and Limits","description":null,"image":"","keywords":null,"jsonLd":null,"lang":null,"siteUrl":null},"pageId":"docs/ai/document-ai/errors-and-limits.md","pageBaseUrl":"/docs/ai/document-ai/errors-and-limits","type":"markdown","toc":{"enable":true,"maxDepth":4,"headings":[{"depth":1,"value":"Errors and Limits","id":"errors-and-limits"},{"depth":2,"value":"Error response format","id":"error-response-format"},{"depth":2,"value":"HTTP status codes","id":"http-status-codes"},{"depth":2,"value":"Upload acceptance and processing eligibility","id":"upload-acceptance-and-processing-eligibility"},{"depth":2,"value":"Retrieve current file limits","id":"retrieve-current-file-limits"},{"depth":2,"value":"Common upload errors","id":"common-upload-errors"},{"depth":2,"value":"Common processing skip reasons","id":"common-processing-skip-reasons"},{"depth":2,"value":"Configuration errors","id":"configuration-errors"},{"depth":2,"value":"Resource lookup errors","id":"resource-lookup-errors"},{"depth":2,"value":"Rate limits","id":"rate-limits"},{"depth":2,"value":"Retry guidance","id":"retry-guidance"}]},"data":{"title":"Errors and Limits"},"catalogInfo":null,"link":"/docs/ai/document-ai/errors-and-limits/","sidebarName":"developerPortal","isLanding":false,"showPrevButton":null,"showNextButton":null,"apiVersions":null,"apiVersionId":null,"isDefaultApiVersion":null}},"staticQueryHashes":["1123603147","1302185487","1344209882","1398840060","1520077861","1975142765","2667623876","2950305614","3240152602","3743992808","561138138"]}