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_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 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