Auth, Requests & Responses

Last Updated: 07 September, 2018

Every request to the ElasticOCR API must include a valid ElasticOCR License ID, and the ID of an App that has been defined within the supplied License/Subscription. App IDs are managed through the portal, and may be used to segment reporting and analytics across multiple source systems and/or business units. Refer to the help documentation for more information about the creation and management of App IDs.

In the event that an invalid License ID/App ID combination is submitted (in the case of an inactive or overdue subscription, or if the supplied App has been disabled), a standard HTTP 401 Unauthorized response will be returned. All API requests must be made over HTTPS, and non-HTTPS requests will fail.

Processing Regions

ElasticOCR guarantees the processing region where your job will be processed. Developers must ensure that requests made to the ElasticOCR API are directed to the appropriate processing region endpoints configured for the account. If the processing region is unknown, a query may be made to the licenses endpoint in any region, to determine the processing region that is configured for the supplied license.

The processingRegion value of this response will match the region code that must be used when querying subsequent calls to the ElasticOCR API. As an example, if sending a License ID and App ID to the licenses endpoint indicated a Processing Region of US, all future calls for that License ID should be made to https://us.api.elasticocr.com. Requests made to an incorrect processing region will fail with an HTTP 401 response because the license is invalid for that region.

Responses

All ElasticOCR API endpoints return conventional HTTP response codes to indicate the success or failure of an API request. 200 level codes indicate successes (we accepted what you sent us), 400 level codes indicate an error in the request (maybe you sent us an incorrect Job ID, or invalid license), and 500 level codes (which are rare) indicate an error on our servers or with our processing of your job.

Success Codes

  • 200 (OK) - The request has succeeded
  • 201 (Created) - The request has been fulfilled and resulted in a new job being created
  • 204 (No Content) - The request has succeeded, but no response object is warranted, as is the case with the deletion of a job

Request Errors

  • 401 (Unauthorized) - Authentication of the request failed, typically due to an invalid License ID/App ID combination or expired license
  • 404 (Not Found) - No result was found for the supplied request, as is the case when querying for an invalid Job ID or invalid endpoint
  • 415 (Unsupported Media Type) - The request was accompanied by a file that was empty or not of a supported file type
  • 429 (Too Many Requests) - The request volume has exceeded the hourly quota permitted by the service tier; a Retry-After header is included to indicate when this interval resets

Server Errors

  • 500 (Internal Server Error) - The server encountered an unexpected condition that will be logged and reviewed by the ElasticOCR team