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"  
      }  
    ]  
  },  
  "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
• file_decryption_failed - Your file is not encrypted with Pagos' public PGP key, or is corrupted
• 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
• file_validation_network_not_available - You don't have a valid MID for this card brand

The value of additional_info property will be a of type string (e.g. Row = 1, Reason = Invalid length of a expiry_year).

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": {  
    "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."  
      }  
    ],  
    "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