API errors

When an API request fails, the server returns an HTTP error code along with a JSON body containing one or more error objects.

Error Codes

HTTP code	Message	Possible causes	Wrong API usage?
400	Bad Request	UNRECOGNIZED_FIELD, UNPARSEABLE_JSON, MISSING_TRANSACTION_TOKEN, BAD_REQUEST	Yes
401	Unauthorized	INVALID_LOGIN_TOKEN, SECURITY_VIOLATION	Yes
404	Not Found	OBJECT_NOT_FOUND	Yes
409	Existing Identification	EXISTING_IDENTIFICATION	Yes
412	Precondition Failed	PRECONDITION_FAILED	Yes
500	Internal Server Error	INTERNAL_SERVER_ERROR	No

Error Causes

Cause	Description
UNRECOGNIZED_FIELD	Your request contains a field not recognized by the system.
UNPARSEABLE_JSON	The JSON body of your request is invalid and cannot be parsed.
MISSING_TRANSACTION_TOKEN	The transaction number or IdentID is missing from your request.
BAD_REQUEST	Your data is badly formatted — for example, a wrong format for a date or country field. Check the key and message fields in the response for details.
INVALID_LOGIN_TOKEN	You provided a wrong API key in the request header.
SECURITY_VIOLATION	You tried to access an identification that does not belong to your account.
OBJECT_NOT_FOUND	You used a wrong URL, or the identification data does not exist. This is also returned when an IdentID has been created but the user has not yet started — or has aborted — the identification process, so no data exists in the backend yet.
EXISTING_IDENTIFICATION	You tried to reuse a transaction number that is already associated with a finished identification. Updating finished identifications is not supported.
PRECONDITION_FAILED	The requested action cannot be performed because a required prerequisite is missing. For example, uploading a contract document before a document definition exists.
INTERNAL_SERVER_ERROR	An unexpected error occurred on the IDnow system. Not caused by incorrect API usage.

Response Structure

All error responses share the same JSON structure:

{
  "errors": [
    {
      "cause": "string",
      "id": "string",
      "key": "string | null",
      "message": "string | null"
    }
  ]
}

Attribute	Description
cause	Short textual identifier for the error (see table above).
id	Unique exception ID. Provide this to IDnow technical support when reporting an issue.
key	The field that caused the error, if applicable (e.g., "birthday").
message	Human-readable error description in English, if available.

Examples

Missing or invalid API key (401)

{
  "errors": [{
    "cause": "INVALID_LOGIN_TOKEN",
    "id": "487800773",
    "key": null,
    "message": null
  }]
}

Badly formatted field (400)

{
  "errors": [{
    "cause": "BAD_REQUEST",
    "id": "73464627",
    "key": "birthday",
    "message": "Please provide a correct value for 'birthday'"
  }]
}

Updating a finished identification (409)

{
  "errors": [{
    "cause": "EXISTING_IDENTIFICATION",
    "id": "34253467",
    "key": null,
    "message": null
  }]
}