---
title: "Incode API Overview"
url: "https://developer.incode.com/general-reference/incode-api-overview/"
section: "general-reference"
group: "Incode API Overview"
version: "v1.1"
status: "live"
---
# Incode API Overview

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.

:::info
  Please check [Get an Access Token](/general-reference/get-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).

:information_source: Some `2XX` responses of the Omni API have a dynamic nature. For example, the [Fetch ocr data](/api-reference/get-ocr-data/) or [Fetch ocr data V2](/api-reference/get-ocr-data-v2/) 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.

:warning: `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.

```json Example response with custom error
 { 
   "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](#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:

1.  `SUPER_HEAVY`: ID endpoints triggered by the SDK normally (e.g. `add/front`, `add/back`, `process/id)`
2.  `HEAVY`: Face endpoints triggered by the SDK normally (e.g. `add/face`, `process/face`)
3.  `OTHER`: All other endpoints

| Category    | maxRps | burst |
| :---------- | :----- | :---- |
| SUPER HEAVY | 1      | 5     |
| HEAVY       | 1      | 5     |
| OTHER       | 100    | 50    |

See [API Rate Limits](/general-reference/rate-limits/) for more information. 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).