API Warnings

Ravelin APIs return warnings when we believe the action we recommend may be suffering from bad or missing data. Warnings have a class, e.g. customer-not-found, a help URL (this page), and description of why the warning has triggered:

POST /v2/checkout?score=true HTTP/1.1
Content-Type: application/json

{
    "timestamp": 1538150837183,
    "customerId": "eg-cust-a",
    "order": {
        "orderId": "eg-order-1",
        "price": 100
    },
    "paymentMethodId": "eg-card-a"
}

200 OK
Content-Type: application/json

{"data": {
    "warnings": [
        {
            "class": "customer-not-found",
            "help": "https://developer.ravelin.com/apis/warnings/#customer-not-found",
            "msg": "Customer \"eg-cust-a\" not found."
        },
        {
            "class": "order-absent-currency",
            "help": "https://developer.ravelin.com/apis/warnings/#order-absent-currency",
            "msg": "Order \"eg-order-1\" does not have a currency."
        }
    ],
    "more": "..."
}}

Handling Warnings

The class on warnings is safe to use programmatically, and suitable for adding to tags in your metrics system for monitoring how frequently you receive these warnings.

Do not throw exceptions when you receive warnings in your API responses. While important to count for regression monitoring and integration improvement, Ravelin’s recommendation action will be best-effort despite the warnings.

Missing Entities

When customer, order, payment method, and transaction data arrives in individual API calls to Ravelin, some data references (e.g. customerId or orderId) may not be resolvable if the request which transmitted the data does not make it to Ravelin, or if the request gets rejected because validation failed.

Bad entity references can be of high impact to Ravelin.

Using /v2/checkout or /v2/travel/checkout and sending full customer, order, payment method, and transaction data each time can mitigate the impact of lost-in-flight data, and minimises the opportunity for using inconsistent identifiers.

Customer Not Found — customer-not-found

No customer with the given customerId exists in Ravelin’s systems.

Order Not Found — order-not-found

No order with the given orderId exists in Ravelin’s systems.

Transaction Not Found — transaction-not-found

No transaction with the given transactionId exists in Ravelin’s systems.

Customer Warnings

Absent Email — customer-absent-email

The customer does not have an email address.

Absent Registration Time — customer-absent-reg-time

The customer does not have a registration time.

If your system supports guest checkout and there is no registration event at which to define a registration time, please use the current time. Ravelin will retain the earliest registration time as a kind of “first seen” time.

Order Warnings

Absent Price — order-absent-price

The order does not have a price.

Absent Currency — order-absent-currency

The order does not have a currency.

Absent Status — order-absent-status

The order does not have a status.

Absent Creation Time — order-absent-creation-time

The order does not have a creation time.

Transaction Warnings

Absent Type — transaction-absent-type

The transaction does not have a type.

Absent Currency — transaction-absent-currency

The transaction does not have a currency.

Absent Amount — transaction-absent-amount

The transaction has no amount.

Absent Payment Method — transaction-absent-paymentmethod

The transaction has no reference to a payment method (either via a paymentMethodId, or by a complete paymentMethod entity sent alongside the transaction).