3DS Error Responses

If a problem occurs during 3DS processing an error response will be returned.

Error Response

The format of the 3DS error response is shown below. Depending on the error, not all fields will be present in the response.

Example Errors

Invalid API Key
HTTP Status 401
Ensure you are using the correct Secret API Key. See Authentication.

{
    "status": 401,
    "timestamp": 1629395847,
    "message": "Unable to verify authentication"
}

HTTP Method is invalid
HTTP Status 405
Ensure you have used the correct HTTP Method (POST, GET) for the request.

{
    "status": 405,
    "timestamp": 1636729123,
    "message": "Method Not Allowed - HTTP method must be POST"
}

Incorrect Content-Type Header
HTTP Status 415
For POST requests the Content-Type header must be application/json; charset=UTF-8.

{
    "status": 415,
    "timestamp": 1636729260,
    "message": "Unsupported Media Type - 'Content-Type' header must be 'application/json; charset=utf-8'"
}

Invalid PAN
HTTP Status 400
The primary account number (PAN) must be numeric, between a length of 13 and 19 digits.

{
    "status": 400,
    "timestamp": 1636733016,
    "message": "Bad Request - pan must be numeric, between a length of 13 and 19 digits"
}

Card is not supported by any of the card schemes for 3DS2
HTTP Status 400

{
  "status": 400,
  "timestamp": 1658926425,
  "message": "Validation error",
  "data": {
    "threeDSServerTransID": "2407c5db-2a35-4dc1-bc5f-8d8fb878ef87",
    "errorCode": "305",
    "errorComponent": "S",
    "errorDescription": "Cardholder Account Number is not in a range belonging to Issuer.",
    "errorDetail": "The card was not supported by any card schemes",
    "errorMessageType": "AReq",
    "messageType": "Erro",
    "messageVersion": "2.2.0"
  }
}

3DS Validation Failures
HTTP Status 400
The request you sent was not a valid 3DS Authenticate Request, address each of the errors.

{
    "status": 400,
    "timestamp": 1629398686,
    "message": "Validation error",
    "cardScheme": "Visa",
    "errors": [
        "browserIP must be a valid IP address",
        "mcc is required when messageCategory is '01'",
        "merchantCountryCode must be 3 characters long",
        "purchaseDate must be in the format YYYYMMDDHHMMSS"
    ],
    "docs": "https://developer.ravelin.com/api/endpoints/3d-secure/authenticate"
}

Timeout reaching directory server
HTTP Status 408 You should retry the request if you receive a timeout, see Retries.

{
    "status": 408,
    "timestamp": 1629400387,
    "cardScheme": "Visa",
    "message": "Ravelin experienced a timeout when sending the authentication request to the directory server."
}

3DS Result could not be found
HTTP Status 404
The threeDSServerTransID in the Result Request could not be found, or it has expired.

{
    "status": 404,
    "timestamp": 1629397969,
    "message": "The 3DS result for the given threeDSServerTransID could not be found"
}

Invalid response received from directory server
HTTP Status 502
The ‘data’ field will contain a 3DS error containing details of the issue Ravelin identified in the directory server’s response. This 3DS error will have been sent to the directory server to notify it of the issue, and is included here for information.

You should restart the 3DS process if you receive a 502 Bad Gateway error, see Retries.

{
    "status": 502,
    "timestamp": 1629400387,
    "cardScheme": "Visa",
    "message": "Ravelin received an invalid response from the directory server. See the 'data' field for the 3DS error message Ravelin has sent to the directory server.",
    "data": {
        "threeDSServerTransID": "c5584543-b67e-5117-bb34-3567ac6a1123",
        "acsTransID": "214a549e-2310-4359-b590-c53a20adcc78",
        "dsTransID": "a3384543-b67e-5117-bb34-4567ac6a1123",
        "errorCode": "203",
        "errorComponent": "S",
        "errorDescription": "Data element not in the required format or value is invalid",
        "errorDetail": "purchaseDate",
        "errorMessageType": "AReq",
        "messageType": "Erro",
        "messageVersion": "2.2.0"
    }
}

3DS error received from directory server
The HTTP Status code will vary depending on the type of 3DS error.
The ‘data’ field will contain the 3DS error Ravelin received from the directory server. The reason for the error could be due to the request content, a 3DS Server issue or a fault with the directory server. This error will have been logged and will be investigated.

If the HTTP status code is 502 or 504 you should restart the 3DS process, see Retries.

{
    "status": 400,
    "timestamp": 1629400387,
    "cardScheme": "Visa",
    "message": "Ravelin received a 3DS error message from the directory server. See the 'data' field for the 3DS error message.",
    "data": {
        "threeDSServerTransID": "c5584543-b67e-5117-bb34-3567ac6a1123",
        "acsTransID": "214a549e-2310-4359-b590-c53a20adcc78",
        "dsTransID": "a3384543-b67e-5117-bb34-4567ac6a1123",
        "errorCode": "203",
        "errorComponent": "D",
        "errorDescription": "Data element not in the required format or value is invalid",
        "errorDetail": "purchaseDate",
        "errorMessageType": "AReq",
        "messageType": "Erro",
        "messageVersion": "2.2.0"
    }
}

Ravelin experienced an internal error
HTTP Status 500
You should retry the request if you receive an internal server error, see Retries.
This will have been logged and will be investigated.

{
    "status": 500,
    "timestamp": 1629397969,
    "message": "Internal Server Error"
}

HTML Error Responses

Under some circumstances the Ravelin 3D Secure API will return errors in an HTML format. These will always be related to an integration issue and should not occur during operation. Several examples are shown below.

Badly formatted GET HTTP Request
HTTP Status 400
GET requests must not contain a body. Ensure you didn’t mean to send a POST request.

400. That’s an error.
Your client has issued a malformed or illegal request.

URL did not use HTTPS
HTTP Status 404
For example, the URL http://3ds.live.pci.ravelin.com/3ds/authenticate is incorrect because it uses http and not https.

404. That’s an error.
The requested URL /3ds/authenticate was not found on this server.

Content-Length Header is missing
HTTP Status 411
All 3D Secure API requests must be sent with a Content-Length header.

400. That’s an error.
POST requests require a Content-length header.

Retries

We have different recommendations for retries depending on the error response HTTP status code.

Timeout - HTTP Status 408
You should immediately retry once if you receive a 408 Timeout error response. You should send the same threeDSServerTransID as used on the original request.

Internal Server Error - HTTP Status 500
You should immediately retry once if you receive a 500 Internal Server Error response. You should send the same threeDSServerTransID as used on the original request.

Bad Gateway - HTTP Status 502
If you receive a 502 Bad Gateway error response you should restart the 3DS process, or end 3DS processing. If you restart the 3DS process you must begin by sending a new Version Request. You must not use the threeDSServerTransID from the original request. A new threeDSServerTransID must be generated. You may need to notify the customer that the 3DS process was restarted.

Gateway Timeout - HTTP Status 504
If you receive a 504 Gateway Timeout error response you should restart the 3DS process, or end 3DS processing. If you restart the 3DS process you must begin by sending a new Version Request. You must not use the threeDSServerTransID from the original request. A new threeDSServerTransID must be generated. You may need to notify the customer that the 3DS process was restarted.

All Other Responses
Do not retry on any other responses. You should investigate the cause of the error. You should notify the customer that 3DS is currently not available.

Feedback

Was this page helpful?

Thanks for the feedback. If you'd like to provide more detail, please email support@ravelin.com.