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 and Dashboard error messages are documented separately.

Error Response Format

All error responses from the Omni API return a JSON object with the following structure:

{
  "timestamp": 1722948860110,
  "status": 4004,
  "error": "Bad Request",
  "message": "Could not find user",
  "path": "/omni/add/front-id/v2"
}

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. */}

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.

User and Identity

These errors indicate that a required user record could not be found or that a conflict exists with existing user data.

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.

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.

Affected endpoints: POST /omni/add/back-id/v2

B2B Integration

These errors are specific to B2B onboarding flows (POST /omni/b2b/onboarding/request-new).

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.

Government Validation (Mexico)

These errors apply to Mexican tax ID and identity validation endpoints.

Score Retrieval

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.

{/* 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.