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:| HTTP Status Code | Code | Message | Details | Endpoint |
|---|---|---|---|---|
| 413 | file_too_big | The request file size exceeds the maximum limit (50 MB). | null | inquiry |
| 403 | unauthorized | Merchant is not authorized to use the resource. | null | inquiry, status, and download |
| 500 | internal_error | An internal error has occurred. | null | inquiry, status, and download |
| 400 | job_not_ready | This job is not ready yet. | null | status and download |
| 404 | job_not_found | A job was not found. | null | status and download |
| 400 | validation_error | Some of the request values failed to validate. | {“jobId”: “Job Id should be numeric”} | status and download |
Status Errors
If your call to request the status of an inquiry successfully reaches the API but the job fails, you’ll receive astatus response of error. The associated error message will appear in the format of the following example:
code property value (and the associated message) can be one of the following:
| code | message |
|---|---|
validation_failed | The file failed to validate. See Details for details. |
invalid_format | The file was in an incorrect format. |
internal_import_error | Internal error while processing the file. |
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 theadditional_infoproperty 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 arevisa,mastercard,discover,american express, andamex_optblue -
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_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
additional_info property will be a type string (e.g. Row = 1, Reason = Invalid length of a expiry_year, Value = 202) and the metadata property will contain the value of the metadata for the row in the submitted job file that produced the error.
Webhook Error Notifications
You’ll receive a Job Failed webhook notification from Pagos whenever a job fails. The notification will appears in the format of the following example:reason field:
-
validation_failed -
invalid_format -
internal_import_error
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_validation_network_not_available
metadata property contains the value of the metadata for the row in the submitted job file that produced the error