Loon API Error Handling

​

Generic API Errors

If your request to submit cards for updates, check the status of an inquiry, or download updated card details fails, you’ll receive a generic API error in the format of the following example:

{
  "error": {
    "code": "validation_error",
    "message": "Some of the request values failed to validate.",
    "details": {
      "JobId": "Job Id should be numeric"
    }
  }
}

What Loon endpoint you call determines the types of HTTP status codes you can potentially receive, should your API request fail. This table outlines the types of generic errors you can receive and what information you can expect to find in the error messaging.

​

Status Errors

If your call to request the status of an inquiry successfully reaches the API but the job fails, you’ll receive a status response of error. The associated error message will appear in the format of the following example:

{
  "status": "error",
  "error": {
    "code": "validation_failed",
    "message": "The file failed to validate. See Details for details.",
    "details": [
      {
        "detail": "file_validation_month_invalid",
        "additional_info": "Row = 1, Reason = Invalid length of a expiry_month",
        "metadata": "[value from the job file for the row]"
      }
    ]
  },
  "networks": [
    {
      "network": "visa",
      "status": "pending"
    },
    {
      "network": "discover",
      "status": "error"
    }
  ]
}

The code property value (and the associated message) can be one of the following:

If the code property value is either invalid_format or validation_failed, then the detail property value—which is enclosed within the details array—can be any of the following:

• file\_format\_error - There is an error in the file’s formatting; review the additional_info property for more details on the formatting error

• file\_decryption\_failed - Your file is not encrypted with Pagos’ public PGP key, or is corrupted; validate that you have registered the appropriate PGP key and are encrypting with the appropriate key

• file\_validation\_network\_invalid - Your file contains an invalid value in the network field; the only possible values in this field are visa, mastercard, discover, and american express

• file\_validation\_month\_invalid - Your file contains an invalid value in the expiry_month field; this value must be in the format of MM

• file\_validation\_year\_invalid - Your file contains an invalid value in the expiry_year field; this value must be in the format of YYYY

• file\_validation\_account\_number\_invalid - Your file contains an invalid value in the account_number field; this value must be 15-16 digits

• file\_validation\_sub\_merchant\_invalid - Your file contains an invalid value in the optional sub_merchant_id field; this value must be alphanumeric

• file\_validation\_metadata\_too\_big - Your file contains a metadata value that exceeds the length maximum of 50 characters

• file\_uniqueness\_check\_failed - Your file contains repeated account_numbers; review the additional_info property for more details on the error

• file\_validation\_network\_not\_available - You’re not registered for account updater services from one or more card brands; reach out to your Pagos account manager

The value of additional_info property will be a type string (e.g. Row = 1, Reason = Invalid length of a expiry_year) and the metadata property will contain the value of the metadata for the row in the submitted Loon job file that produced the error.

​

Webhook Error Notifications

You’ll receive a Job Failed webhook notification from Loon whenever a job fails. The notification will appears in the format of the following example:

{
  "type": "wh_job_failed",
  "data": {
    "merchantId": "9bb8592c-cb99-48f7-907e-f97de930fc5c",
    "job_id": 54321,
    "reason": "validation_failed",
    "error_details": [
      {
        "detail": "file_validation_network_invalid",
        "additional_info": "A duplicate account number was found on line number 4345.",
        "metadata": "[value from the job file for the row]"
      }
    ],
    "timestamp": "2023-11-16T22:30:45.678Z"
  }
}

This notification will always include one of the following values in the reason field:

• validation\_failed

• invalid\_format

• internal\_import\_error

The JSON array error_details can have one or more items with the following string values in the detail property and details in additional_info:

• file\_format\_error

• file\_decryption\_failed

• file\_validation\_network\_invalid

• file\_validation\_month\_invalid

• file\_validation\_year\_invalid

• file\_validation\_account\_number\_invalid

• file\_validation\_sub\_merchant\_invalid

• file\_validation\_metadata\_too\_big

• file\_uniqueness\_check\_failed

• file\_validation\_network\_not\_available

The metadata property contains the value of the metadata for the row in the submitted Loon job file that produced the error