Generic Error Response

In general, when an error occurred, the endpoint returns an error response in the following structure.

{
    "error": {
        "code": ERROR_CODE,
        "message": "ERROR_MESSAGE"
    },
    "status": "failed"
}

Depends on the error code, some error might include additional information on the error and being under "info" in "error".

Failed Extraction Result

When using Document Extraction API (/v2/extract and /v2/extract/jobs/{job_id}), a single request could lead to multiple document extractions, and each of them could be failed separately.

When only some of the document extractions in a single request failed, you will get a success response with status code 200 but with failed extraction result. The structure will be as following.

{
  "documents": [
  	{
      "extractor_id": EXTRACTOR_ID_USED,
      "metadata": {
      	"page_no": 1,
      	"slice_no": 1
    	},
      "error": {
        "code": ERROR_CODE,
        "message": ERROR_MESSAGE
      }
  	}
  ],
  "metadata": {
    "extractor_id": EXTRACTOR_ID_SPECIFIED,
    "request_id": REQUEST_ID,
    "usage": 0
  },
  "status": "ok"
}

Error Codes

Following are the list of error codes and the corresponding HTTP status codes when it is being used in a generic error response.

Noticed that when the error code is being used in a single failed extractor result, the status codes are ignored, the caller will always get a success response with HTTP 200 status code.

1xxx Errors

Error codes start with 1xxx are error occurs before the extraction process begin. This could mean invalid parameters in the request, rate limit or usage quota exceeded.

Error Code	Error Message	Status Code
1001	Invalid token	403
1001	Invalid argument(s)	400
1002	"X-WORKER-EXTRACTOR-ID" in header or "extractor_id" in multipart/form-data is required	400
1003	Image URL should start with "http://" or "https://"; and the host cannot be "127.0.0.1" or "localhost"	400
1004	Cannot load image from provided image URL or file. Please ensure the URL is correct, publicly accessible, or the file is a valid, supported format.	400
1005	Uploaded file is too large, should be less than 10.0MB	413
1006	Usage quota exceeded, please upgrade to continue	402
1007	Too many requests	429
1009	Image dimension is too large. The image width or height should be < 11999px and total number of pixels should be <= 75000000	400
1010	Unauthorized	401
1011	"X-WORKER-WORKSPACE-ID" in header or "workspace_id" in multipart/form-data is required	400

2xxx Errors

Conversely, error codes starts with 2xxx are errors occur during the extraction process. It can be misconfiguration of the extractors or temporary server error. The status code could be 200 or those specified below depends on wether all document extraction processes failed. Please see the "Error Handling" in the next section for next steps.

Code	Message	Status Code
2001	Extractor ID not found	404
2002	No Anchor Region is set up on the master image in fixed layout extractor	400
2003	Failed to match the image features on input image with the master image in fixed layout extractor	400
2004	Unknown error during extraction, please try again later.	500
2005	Extractor ID (Combined Extractor) not found	404
2006	Combined extractor has no extractors configured	400
2007	Cannot recognize any text from the input image	400
2008	Error during extraction (Script)	400
2009	Custom model extractor schema is not defined	400
2010	Error during extraction, please try again later (LLM)	500
2011	Error during extraction (LLM token length exceeded)	400
2013	Workspace ID not found	404
2014	Workspace is not linked to the any extractor	400
2015	Invalid post processing result, please check the post processing script	400
2016	Error during extraction, please try again later (Inferencer client error: Unknown server error [detect-multi-document-inferencer])	500
2017	Error during extraction, please try again later (Invalid inferencer response [detect-multi-document-inferencer])	500
2018	Error during extraction, please try again later (Inferencer request error [detect-multi-document-inferencer])	500
2019	Recognizer is not available under current extractor configuration. If you are using Azure or Google OCR, please make sure crediential are set and valid.	400
2020	Error during extraction, please try again later (RecognizerError)	500
2021	Poor image quality, reason: blurry	400

4xxx Errors

Error codes start with 4xxx are error occurs during starting an async extraction, or later getting the async extraction result or workspace extraction result. It can be due to specifying the wrong ID or there are some temporary server error when retrieving the result.

Code	Message	Status Code
4001	Extract job not found	404
4002	Fail to submit extract job, please try again later	500
4003	Extraction result not found in workspace	404
4004	Unexpected extraction result in workspace: Unknown extraction	400
4005	Cannot retrieve extraction result in workspace, please try again later	500

7xxx Errors

Error codes start with 7xxx are error occurs while getting the retained extraction file or result. It can be due to specifying the wrong request ID or there are some temporary server error when retrieving the file or result.

Code	Message	Status Code
7001	Extraction retention not found	404
7002	Temporarily not able to retrieve the retention data, please try again later	500

8xxx Errors

Error codes start with 8xxx are error occurs while adding or updating training sample to accuracy center. It can be due to specifying the wrong document ID, already import a training sample from datalog, or the supplied ground truth data is invalid according to the extractor schema.

Code	Message	Status Code
8001	Cannot find document in accuracy center. You can import document to accuracy center by calling /v2/accuracy-center/document/import-from-datalog.	404
8002	Cannot find document in datalog. You should call /v2/extract or /v2/workspace with datalog enabled.	404
8003	Ground truth data is invalid according to the latest schema.	400
8004	Document already imported in the accuracy center.	400

9xxx Errors

Error codes start with 9xxx are error occurs while generate PUT url for file upload. It can be due to temporary server error when generating the PUT url.

Code	Message	Status Code
9001	Cannot generate PUT url for file upload at this moment, please try again later.	500

Error Handling

In general, unless it is stated in the error message that the caller can try again the request later, it is expected the caller to carried out some action in order to resolve the error.

Correct the request parameter

If you are getting 1001,1002,1010, please make sure, Access Token, Extractor ID/Workspace ID or other request parameter are correctly specified according to API Reference

You should be able to get the Access Token, Extractor ID/Workspace ID from the "API" tab in FormX Portal after you select an Extractor/Workspace.

Resize or replace the input image or PDF

If you are getting 1005 or 1009, please ensure the input image are within our dimension and file size limit.

To get best extraction result, please refer to Image Image Upload Best Practice

If you are getting 1003 or 1004, please double check the upload file or the specified image url, and make sure they could resolve to a uncorrupted, supported image or PDF file.

Reaching Usage Quota

If you are getting 1005, you have used up the assigned quota, please upgrade or contact us.

Reaching Rate Limit

If you are getting 1007, you are calling the endpoint too frequent.

All endpoints unless specified have rate limit of 50 requests per minute.
/v2/extract/jobs/{job_id}has rate limit of 500 requests per minute.

Correct the Extractor configuration

If you are getting error code above 2000, and it didn't mention "please try again later" in the error message, this usually imply there are some incorrect configuration on the specified extractor.

Please try to correct the configuration in FormX Portal according to the error message.
If you need any help please contact us.