# API Error Codes
The Incode Omni API uses standard HTTP status codes to indicate whether a request succeeded or failed. For certain errors, the response body also contains an Incode-specific status code that provides more precise information about what went wrong.
This page covers API error codes. [SDK error handling](https://developer.incode.com/docs/sdk-error-handling) and Dashboard error messages are documented separately.
### **Looking for SDK errors?**
SDK error handling documentation is coming soon. In the meantime, refer to the error handling section in each platform's integration guide.
***
## Error Response Format
All error responses from the Omni API return a JSON object with the following structure:
```json
{
"timestamp": 1722948860110,
"status": 4004,
"error": "Bad Request",
"message": "Could not find user",
"path": "/omni/add/front-id/v2"
}
```
| Field | Type | Description |
| ----------- | ------- | -------------------------------------------------------------------- |
| `timestamp` | integer | UTC timestamp of the error, in milliseconds |
| `status` | integer | HTTP status code, or an Incode custom error code for `400` responses |
| `error` | string | HTTP status text (e.g., `"Bad Request"`, `"Forbidden"`) |
| `message` | string | Human-readable description of the error |
| `path` | string | The endpoint path that returned the error |
| `details` | object | Additional error context, when present |
### **Custom error codes and HTTP status**
When an Incode custom error code is returned, the `status` field in the response body will contain the custom code (e.g., `4004`) rather than the HTTP status code. The HTTP status of the response itself will still be `400`.
***
## HTTP Status Codes
The following standard HTTP status codes are used across the Omni API.
{/* REVIEW: Verify whether 401 Unauthorized should be added to this table. See review note 4. */}
| Code | Name | Description |
| ----- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | OK | The request succeeded. |
| `400` | Bad Request | The request was invalid. This may be due to missing or malformed parameters, or an Incode-specific condition described by a custom error code in the response body. |
| `403` | Forbidden | The request is not permitted. This can occur when a feature is disabled for your organization (for example, score retrieval). |
| `429` | Too Many Requests | The request was rate-limited. A cooldown period must complete before retrying. This applies to OTP send operations. |
| `500` | Internal Server Error | An unexpected error occurred on Incode's servers. |
| `504` | Gateway Timeout | The request exceeded the allowed time limit. This can occur during external validation operations such as CURP validation. |
***
## Incode Custom Error Codes
When a request fails with a `400` response, the `status` field in the response body may contain an Incode-specific error code. These codes provide more precise information than the HTTP status alone.
Custom error codes are grouped below by functional area.
***
### Session Initialization
These errors are returned by `POST /omni/start` when a session cannot be created due to configuration or parameter issues.
| Code | Message | Description |
| ------ | ------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `4026` | Invalid uuid parameter | The `uuid` parameter provided is not valid. |
| `4027` | Invalid configurationId | The `configurationId` does not correspond to a valid configuration. |
| `4028` | Flow is not activated | The specified Flow or Workflow has not been activated. Activate it in the Dashboard before use. |
| `4081` | Invalid parameters for validation | One or more parameters failed validation on session start. |
| `4082` | Start endpoint version forbidden in flow/workflow | The version of the `/omni/start` endpoint used is not permitted by the configured Flow or Workflow. |
***
### User and Identity
These errors indicate that a required user record could not be found or that a conflict exists with existing user data.
| Code | Message | Returned by |
| ------ | ------------------------------------ | ----------------------------------------------------------------------------------------- |
| `4004` | Could not find user | `POST /omni/external/send-sms`, `POST /omni/add/front-id/v2`, `POST /omni/add/back-id/v2` |
| `4006` | User with given phone already exists | `POST /omni/process/approve` |
***
### Face and Selfie Processing
These errors are returned when a face or selfie image cannot be processed successfully. They are most commonly returned by ID upload and face capture endpoints.
| Code | Message | Description |
| ------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `1003` | Face cropping failure | A face was detected in the image but could not be cropped successfully. |
| `4010` | More than one face detected | The image contains multiple faces. Only a single face is expected. |
| `4019` | Face not found | No face was detected in the submitted image. |
| `4077` | Selfie image has low quality | The selfie image does not meet minimum quality requirements. |
| `4078` | Selfie face is occluded or partially covered | The face in the selfie is obscured. Prompt the user to remove obstructions (glasses, masks, hands) and retry. |
**Affected endpoints:** `POST /omni/add/front-id/v2`, `POST /omni/add/front-second-id/v2`, `POST /omni/add/face/third-party`
***
### Image Quality
{/* REVIEW: Consider merging this section into "Face and Selfie Processing" if no additional
image quality codes are expected. See review note 3. */}
These errors indicate that a submitted image does not meet technical requirements.
| Code | Message | Description |
| ------ | ---------------------- | ------------------------------------------------------ |
| `5003` | Unsatisfied image size | The image does not meet the minimum size requirements. |
**Affected endpoints:** `POST /omni/add/back-id/v2`
***
### B2B Integration
These errors are specific to B2B onboarding flows (`POST /omni/b2b/onboarding/request-new`).
| Code | Message | Description |
| ------ | ---------------------------------------- | --------------------------------------------------------------------------- |
| `4300` | Integration not found by id | The integration ID provided does not match a known integration. |
| `4301` | Employee by login factor cannot be found | An employee record matching the provided login factor could not be located. |
***
### OTP and Contact Verification
{/* REVIEW: Verify the HTTP method for /omni/send/otp. The spec lists it as GET but send
operations are typically POST. Correct the method below if needed. See review note 2. */}
These errors are returned by `GET /omni/send/otp`.
| HTTP Code | Message | Description |
| --------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `400` | Contact Already Verified | The phone number or email address is already verified for this session. |
| `429` | Cooldown period not completed | An OTP was recently sent to this contact. Wait for the cooldown period to expire before requesting a new one. |
***
### Government Validation (Mexico)
These errors apply to Mexican tax ID and identity validation endpoints.
| HTTP Code | Endpoint | Description |
| --------- | ------------------------- | ------------------------------------------------------------ |
| `400` | `POST /api/validate/rfc` | Invalid RFC format. |
| `400` | `POST /api/calculate/rfc` | Invalid input data provided for RFC calculation. |
| `500` | `POST /api/validate/rfc` | Internal server error during RFC validation. |
| `500` | `POST /api/calculate/rfc` | Internal server error during RFC calculation. |
| `500` | CURP validation endpoints | Internal error during CURP validation. |
| `504` | CURP validation endpoints | The CURP validation request exceeded the allowed time limit. |
***
### Score Retrieval
| HTTP Code | Endpoint | Description |
| --------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `403` | `GET /omni/get/score` | Score retrieval is disabled for this organization for session users. Contact your Incode account team to enable this feature. |
***
## Known Gaps
The API specification documents custom error codes for a subset of endpoints. Many endpoints that return `400 Bad Request` do not currently have custom error codes defined in the API spec. If you encounter a `400` response without a custom code from an endpoint not listed above, the `message` field in the response body is the best available source of information about the specific failure.
### **Content in progress**
This reference will be updated as custom error codes are confirmed for additional endpoints. If you encounter an undocumented error code, contact [Incode Support](#) or your customer success manager.
{/* REVIEW: Replace the two placeholder links (#) above and in "Handling Errors" below with
the correct URLs before publishing. See review note 5. */}
***
## Handling Errors
A few general practices for handling Omni API errors:
**For **`400`** errors:** Check the `status` field in the response body first. If it contains a value from the custom error code tables above, use that to determine the specific failure. If `status` is `400`, fall back to the `message` field.
**For **`429`** errors:** Implement a retry with a backoff delay. Do not retry immediately — the response indicates a cooldown period is required.
**For **`500`** and **`504`** errors:** These indicate a server-side or timeout condition. Retry with exponential backoff. If errors persist, check the [Incode Status Page](#) for any ongoing incidents.
**For **`403`** errors:** These are typically configuration issues, not transient failures. Retrying will not resolve them — contact your Incode account team.