The Incode Omni API is organized around REST. In general our API uses standard secure HTTP requests with JSON arguments and JSON responses.
Authentication
REST API calls must be authenticated using a custom HTTP header X-Incode-Hardware-Id
— along with a JSON web token. Additionally, every API call has to contain x-api-key
header with valid client API key.
Please check the section Create an Access Token for an explanation of how access tokens are generated and used
API Responses
Incode Omni uses conventional HTTP response codes to indicate the success or failure of an API request. In general:
- Codes in the
2XX
range indicate success. - Codes in the
4xx
range indicate an error that failed given the information provided (e.g. missing required parameter). These usually mean you need to fix your request. - Codes in the
5xx
range indicate server side errors (these are rare).
ℹ️ Some 2XX
responses of the Omni API have a dynamic nature. For example, the Fetch ocr data endpoint will might contain additional fields depending on the data which was extracted from provided ID Document in the session. If you are using typed languages such as Java or C#, consider these cases to avoid having serialization exception when reading the JSON responses.
⚠️ 4XX
errors that can be handled programmatically on your end include status of an error and message that briefly explains the error reported.
Arguments:
- timestamp: Long, UTC timestamp in milliseconds
- status: Integer, custom error code or http status code
- error: String, Http status error
- message: String, custom error message
- path: String, endpoint path
Custom error codes are given for each endpoint.
{
"timestamp": 1584639032757,
"status": 405,
"error": "Spoof attempt detected",
"message": "BadRequestException: Spoof attempt detected.",
"path": "/omni/add/face"
}
HTTP status code summary:
200
(OK) - Everything worked as expected.400
(Bad Request) - The request was unacceptable, often due to missing a required parameter.401
(Unauthorized) - Invalid or missing access token.403
(Forbidden) - Invalid or missing api key.404
(Not Found) - The requested resource doesn't exist.405
(Method Not Allowed) - Unacceptable HTTP method for requested resource.406
(Not Acceptable) - Unacceptable request.429
(Too Many Requests) - See rate limits below.500, 502, 503, 504
(Server Errors) - Something went wrong on server side. (These are rare.) :
API Limitations
Maximum Request Size
There is a limitation of 10Mb as the maximum possible request / response size in all our API endpoints, for this reason; it's is not possible to upload or fetch images/files larger than 10 Mb.
Timeout
There is a hard limit of 30 seconds for all of our endpoints. If any request takes longer than that, you will receive a Request Timeout
error
Rate limits
We rate limit our APIs via throttling based on the "tokens in a bucket" approach:
- Each endpoint call requires a token (each organization has a bucket of tokens per endpoint category)
- Bucket capacity (
burst
) defines how many tokens can be withdrawn at once - Tokens are refilled until the bucket reaches maximum capacity based on the refill rate (
maxRps
)
There are three endpoint categories, each one with its own bucket:
-
SUPER_HEAVY
: ID endpoints triggered by the SDK normally (e.g.add/front
,add/back
,process/id)
-
HEAVY
: Face endpoints triggered by the SDK normally (e.g.add/face
,process/face
) -
OTHER
: All other endpoints
Category | maxRps | burst |
---|---|---|
SUPER HEAVY | 1 | 5 |
HEAVY | 1 | 5 |
OTHER | 100 | 50 |
For special cases (only) where these limits are not enough, our Customer Success team can help you adjust as needed.
Rate limit example:
The endpoints add/front
add/back
and process/id
are in the SUPER_HEAVY
category. The maximum bucket capacity is 5
, meaning the max amount of requests that can be done in a second is 5. Every request will deplenish the bucket by 1. If all 5 requests are consumed within the same second the bucket is emptied, any additional requests within the same second will receive the response: 429 Too Many Requests
.
The SUPER_HEAVY
bucket has a refill rate of 1 (maxRps
) per second, so it will refill by 1 unit every second until it's filled (5).