Error Handling

Berkeley follows standard HTTP response status codes to indicate success or failure of an API request.

All HTTP response status codes are separated into five classes (or categories). The first digit of the status code defines the class of response. The last two digits do not have any class or categorization role. Berkeley will return codes in the following ranges:

• 2xx (Successful): The request was successfully received, understood, and accepted
• 4xx (Client Error): The request contains bad syntax or cannot be fulfilled
• 5xx (Server Error): The server failed to fulfill an apparently valid request

In the rare case of an error with Berkeley's system a 500 status code will be returned and the error message will contain an error code of internal_error.

Generic Errors

There are a few generic error codes that apply to any type of request. The following lists the error codes you may encounter when making an HTTP request into the Berkeley API.

The following table lists all the generic errors codes and messages.

Card Issuing Errors

If a request fails due to a client error it will contain a 400 HTTP status code with the corresponding body following below:

{
       "error": {
           "message": "Human readable error message, subject to change",
           "code": "Error code that can be programmatically checked against"
       }
}

Additional fields may be included when described below.

If a request fails with a 5xx series error the response will contain a tracking code. The example below shows the body of an HTTP 500 (Internal Server) error:

{
        "error": {
            "code": "internal_server_error",
            "message": "Internal Server Error",
            "tracking_code": "41519fff-439c-4d3d-ab33-4b74c763d2de"
        }
}

When reporting an issue, please return the "tracking_code" field to Berkeley to aid in resolving the issue.

CARD ISSUING - TRANSACTION ERROR CODES

CARD ISSUING - KYC RESULTS

KYC Verifications will be rejected or sent for manual approval if the consumer information provided as part of the Create Cardholder is not correct or does not match the database records of our KYC provider. For a list of test cases, please go to this page

If a request is unsuccessful then it will contain a 400 status code with the corresponding body following below:

    {
        "code": "kyc_verification_rejected",
        "message": "The cardholder was rejected due to KYC verification failure.",
        "kyc_result_codes": [
                {
                    "code": "street_mismatch",
                    "description": "Street does not match records",
                    "found": "ENGELMANN DR",
                    "match_type": "partial_match",
                    "value": "49 ENGLEMANN DR"
                },
                {
                    "code": "insufficient_credit_record",
                    "description": "Insufficient credit history for a match"
                }
        ],
        "kyc_transaction_id": "bca156b3-0668-49f7-bdf8-11cc6b628120"
    }

KYC RESULT CODES

There are a number of result messages that can be returned when a KYC verification is executed. The full list of KYC result descriptions can be found here.

Card Issuing - Validation Failures

When a model fails validation, a field_errors field will be attached to the error message describing why each failing field did not pass validation. An example is below:

    {
        "error": {
            "code": "invalid_object",
            "field_errors": [
                {
                    "code": "valid_field",
                    "message": "Field Failed to pass validation",
                    "position": [
                        "test"
                    ],
                    "value": "Test"
                }
            ],
            "message": "Invalid field(s) in Object"
        }
    }

Possible fields for fields errors are:

DirectSend - Tokenization Errors

Tokenization errors may occur due to reasons as explained below. If a request fails and throws an error it will contain a 400 HTTP status code with the corresponding body following below:

    {
        "error": {
            "message": "Human readable error message, subject to change",
            "code": "Error code that can be programmatically checked against",
            "transaction_id": // With be part of response if this error was part of a transaction request
        }
    
    }

TOKENIZATION ERROR CODES

DirectSend - Account Holder Errors

There are a few error codes related to Account Holders. The following lists the error codes you may encounter when making an HTTP request into the Berkeley API.

ACCOUNT HOLDER ERROR CODES

The following table lists all the errors codes and messages.

DirectSend - Financial Account Errors

There are a few error codes related to Financial Accounts The following lists the error codes you may encounter when making an HTTP request into the Berkeley API.

FINANCIAL ACCOUNT ERROR CODES

The following table lists all the errors codes and messages.

DirectSend - Transaction Errors

Transaction errors may occur due to reasons such as: invalid card information, the inability to process a transction on a payment network, etc.

If a request is unsuccessful then it will contain a 400 or 500 status code with the corresponding body following below:

    {
        "error": {
            "message": "Human readable error message, subject to change",
            "code": "Error code that can be programmatically checked against",
            "transaction_id": // Will be part of response if this error was part of a transaction request
        }
    
    }

TRANSACTION ERROR CODES

The following table lists all the errors codes and messages.

DirectSend - 3D-Secure Errors

There are a few error codes related to 3DSecure Authentications. The following lists the error codes you may encounter when making an HTTP request into the Berkeley API.

3D-SECURE ERROR CODES

The following table lists all the errors codes and messages.