> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pagos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch Account Updater API Error Handling

## Generic API Errors

If your request to [submit cards for updates](/account-updater/endpoint/inquiries), [check the status of an inquiry](/account-updater/endpoint/status), or [download updated card details](/account-updater/endpoint/download) 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           |

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

What 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](/account-updater/batch-api-overview#check-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:

```json theme={null}
{
  "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:

| 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.`             |

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`, `american express`, and `amex_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

The value of `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](/account-updater/batch-webhooks#job-failed) from Pagos whenever a job fails. The notification will appears in the format of the following example:

```json theme={null}
{
  "type": "wh_job_failed",
  "data": {
    "merchantId": "9bb8592c-cb99-48f7-907e-f97de930fc5c",
    "job_id": 54321,
    "reason": "validation_failed",
    "error_details": [
      {
        "detail": "file_validation_year_invalid",
        "additional_info": "Row = 911, Reason = Invalid length of a expiry_year, Value = 202",
        "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_validation_network_not_available`

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