HTTP status codes and response formats

The server can return the following HTTP status codes:

  • 200 – successful method call
  • 4xx – incorrect parameters of the method
  • 5xx – an error on the server side

The body of the response contains JSON. The standard response formats are described below.

Response format for the status code 200

  "taskId": <task guid>,
  "registrationTime": <task creation time>,
  "statusChangeTime": <status change time>,
  "status": <status>,
  "filesCount": <amount of submitted files>,
  "error": <error text>,
  "requestStatusDelay": <recommended delay before next gettaskstatus request in ms>,
  "resultUrls": [
  "description": <description>
  • resultUrls – this attribute is an array that provides up to 3 URLs. The first URL is only available for completed tasks. It contains the result of processing.

    The GET request to download the result should not include any authorization headers. Using your Cloud OCR SDK authorization headers will result in an error.

    The second URL is available for completed tasks which were processed with multiple export formats. It contains the result saved in the second specified format. 

    The third URL is available for completed tasks which were processed with three export formats. It contains the result saved in the third specified format.

    The hyperlinks have limited lifetime. If you want to download the result after that time has passed, use the getTaskStatus or listTasks method to obtain the new hyperlink.
  • filesCount – specifies the number of files in the task.
  • requestStatusDelay – estimated time until the task is completed (in milliseconds). This attribute is available for the tasks with Queued or InProgress status.
  • error – description of the error occurred during processing. This attribute is available for the tasks with ProcessingFailed status only.

We do not recommend sending the same file for processing repeatedly, if the first task failed. However, if you have created several tasks for the same file, and all of them have failed, the fullest and most specific error description can be received by calling getTaskStatus for the first of those tasks.

Response format for the status codes 4xx and 5xx

    "code":<error internal name>,
    "message":<error message>,
    "target":<target argument>,
        "code":<validation error internal name>,
        "target":<target argument>,
        "message":<error message>
  • code – an internal unique name of the occurred error. Possible error names are described in the table below.
  • message – a human-readable error description.
  • target – the request argument causing the error, i.e. in case required taskId argument was not specified, target element will store a value "taskId". This parameter is optional.
  • details – an array of error objects, returned for InvalidArgument errors with HTTP response status code 400. Every array element corresponds to one of possible errors in request arguments, i.e. an invalid value of the argument. Every error has its own internal name, returned in the code element, an argument causing the error in target element (optional) and description in the message element. The details element itself is optional.

Status codes and response format

General status codes and response format of the method are described in the table below. 

Code Error Name Description
200   Successful method call.
400 InvalidArgument

One or more arguments are incorrect. See the table below this one for details.

402 NotEnoughUnits You have reached the the limit of images that you can process on your account. This issue can be resolved by topping up your account.
QuotaExceeded Exceeded quota to add images. This error is returned if the number of images you have uploaded exceeds the number of images you can process with the credits available on your account plus some threshold. You can resolve this issue by removing the tasks which have been submitted but have not been processed.
409 InvalidTaskState The request could not be completed due to a conflict with the current state of the target resource. I.e., a task that is supposed to be deleted is currently in progress.
422 FileWrongAccessPassword Incorrect password for accessing password-protected image file has been specified.
FileHasAccessRestrictions Access errors inside the uploaded file. 
FileFormatUnsupported Uploaded file format is not supported and cannot be processed.
FileCantOpenImage Internal error occurred while opening the image file.
500 InternalServerError An internal server error occurred.

Below you can find variations of the InvalidArgument error with code 400:

Error name Description
InvalidParameterName One or more arguments have invalid name.
InvalidParameterValue One or more passed parameters are set to invalid values. I.e., task description length exceeds 255 characters.
MissingArgument One or more arguments are expected. I.e., the task identifier has not been specified.
ConflictingParameters Some parameters cannot be set to specified values simultanuosly. I.e. handprinted text type is not supported for the specified languages.

Have more questions? Submit a request



Please sign in to leave a comment.