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.

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.

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.

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.

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.