# Error Codes and Payload Formats
source: https://developer.mastercard.com/automatic-billing-updater/documentation/codes-and-formats/index.md
## Errors Overview {#errors-overview}
We use standard HTTP response codes for success and failure notifications. In general, 200 codes correspond to success, 4xx codes are for developer- or user-related failures, and 5xx codes are for Mastercard-related issues.
| HTTP Status Code | Response | Description |
|------------------|-------------------|--------------------------------------------------------------------------------------------------------------------------|
| 200 | OK | The request was completed successfully |
| 400 | BAD REQUEST | The request was unacceptable, often due to a missing or incorrectly formatted parameter |
| 401 | UNAUTHORIZED | Not authorized to access the service. Missing or invalid authentication credentials provided for the requested resource. |
| 429 | TOO MANY REQUESTS | Too many requests hit the service too quickly |
### Error structure {#error-structure}
All error responses for the Automatic Billing Updater (ABU) API adopt the following payload format:
| Field | Description |
|-----------------|------------------------------------------------------------------------------------------------------------------|
| **Source** | How the error was generated |
| **ReasonCode** | A unique code identifying the error case encountered during transaction processing |
| **Description** | Description of the `ReasonCode` field with additional details |
| **Recoverable** | Indicates whether this error will always be returned for this request, or if retrying might change the outcome |
| **Details** | Additional information about data received and calculated during request processing to help with troubleshooting |
#### Single error structure {#single-error-structure}
```json
{
"Errors":{
"Error":[
{
"Source":"",
"ReasonCode":"",
"Description":"",
"Recoverable":true/false,
"Details":""
}
]
}
}
```
#### Multiple errors structure {#multiple-errors-structure}
```json
{
"Errors": {
"Error": [
{
"Source": "",
"ReasonCode": "",
"Description": "",
"Recoverable": true/false,
"Details": ""
},
{
"Source": "",
"ReasonCode": "",
"Description": "",
"Recoverable": true/false,
"Details": ""
}
]
}
}
```
## Gateway Errors {#gateway-errors}
Under certain conditions, you may receive 4xx/5xx errors from our API gateway. Every error message that is generated and returned by the API gateway will have a value of `Gateway`.
See gateway error codes [here](https://developer.mastercard.com/platform/documentation/security-and-authentication/gateway-error-codes/).
Tip: Every error message that is generated and returned by the API gateway will have a value of `Gateway`. Note: ABU updated the error responses sent for API gateway errors. Changes are effective from **17 July 2024**.
If you implemented the ABU API before this date, refer to [GLB 9378.1 Automatic Billing Updater API Error Response Changes](https://trc-techresource.mastercard.com/r/bundle/m_an9378_en-us/page/d/en-US) on the Technical Resource Center via Mastercard Connect for more details on changes to the API gateway error responses for ABU services.
## Application Errors {#application-errors}
ABU may respond with the following error codes if the API request failed certain conditions:
| Status Code | Source | ReasonCode | Description / Details | Resolution |
|-------------|-----------------------|--------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 400 | `System` | `INVALID_INPUT_FORMAT` | Can be returned by any endpoint if the request contains invalid characters. | Check API specifications for schema, data type, minLength, maxLength and if a required field is missing |
| 400 | `Validation` | `SYSTEM_ERROR` | Can be returned by any endpoint if a parameter value is invalid. | Check API specifications for allowed request parameters |
| 400 | `Validation` | `INVALID_EXPIRY_DATE` | Expiry is greater than 12 months in the past. Returned by `/subscriptions` when the expiry date submitted is out of range. | Not applicable ABU does not accept subscription requests for account information submitted with an expiry date older than 12 months |
| 400 | `Validation` | `INVALID_PARAM` | Invalid or unavailable inquirer information. Returned by `/inquiries` or `/subscription-inquiries` when the inquirer details submitted are invalid. | Ensure your ICA is enrolled in ABU and onboarded for the API service before retrying with a valid ICA |
| 400 | `Validation` | `INVALID_PARAM` | Invalid or unavailable merchant and/or aggregator information. Can be returned by any endpoint when the merchant/aggregator details submitted are invalid. | Confirm the `merchantId`, and `subMerchantId` where used, are registered with ABU under the ICA in the request, then retry with the registered values. See [Participating in ABU](https://developer.mastercard.com/automatic-billing-updater/documentation/support/index.md) for the merchant registration methods |
| 400 | `Validation` | `SUBMISSION_ERROR_TOKEN_VALUE` | Cannot subscribe to a network token value. Returned by `/subscriptions` only, when the account submitted is a network token. | Not applicable ABU Push model does not support network (MDES) tokens |
| 401 | `Security.Credential` | `AUTHENTICATION_FAILED` | Unauthorized Access to Web Service | Ensure your clientId has been onboarded, then retry with valid credentials You may receive this error if your ABU API keys have expired. Contact [API Support](mailto:APISupport@mastercard.com) |
| 429 | `System` | `SYSTEM_ERROR` | Too many requests | Reduce your request rate, then retry the request after a short delay, increasing the wait after each repeated 429 Returned when the request volume from your client exceeds the allowed rate. Note: You may also receive a 429 error response from the API gateway. Check [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/security-and-authentication/gateway-error-codes/) for more details. |
### Sample error response payloads {#sample-error-response-payloads}
```json
{
"Errors":{
"Error":[
{
"Source":"System",
"ReasonCode":"INVALID_INPUT_FORMAT",
"Description":"Invalid characters",
"Recoverable":false,
"Details":"Bad Request"
}
]
}
}
```
```json
{
"Errors":{
"Error":[
{
"Source":"Validation",
"ReasonCode":"SYSTEM_ERROR",
"Description":"Invalid value for parameter",
"Recoverable":false,
"Details":"Invalid Params"
}
]
}
}
```
```json
{
"Errors":{
"Error":[
{
"Source":"Validation",
"ReasonCode":"INVALID_EXPIRY_DATE",
"Description":"Invalid Params",
"Recoverable":false,
"Details":"Expiry is greater than 12 months in the past"
}
]
}
}
```
```json
{
"Errors":{
"Error":[
{
"Source":"Validation",
"ReasonCode":"INVALID_PARAM",
"Description":"Invalid or Unavailable Inquirer information. Please check.",
"Recoverable":false,
"Details":"Invalid Params"
}
]
}
}
```
```json
{
"Errors":{
"Error":[
{
"Source":"Validation",
"ReasonCode":"INVALID_PARAM",
"Description":"Invalid or Unavailable Merchant and/or Aggregator information. Please check",
"Recoverable":false,
"Details":"Invalid Params"
}
]
}
}
```
```json
{
"Errors":{
"Error":[
{
"Source":"Validation",
"ReasonCode":"SUBMISSION_ERROR_TOKEN_VALUE",
"Description":"Cannot subscribe to a network token value for ABU Push",
"Recoverable":false,
"Details":"Invalid Params"
}
]
}
}
```
```json
{
"Errors":{
"Error":[
{
"Source":"Security.Credential",
"ReasonCode":"AUTHENTICATION_FAILED",
"Description":"Unauthorized Access to Web Service",
"Recoverable":false,
"Details":"exceptionMessage"
}
]
}
}
```
```json
{
"Errors":{
"Error":[
{
"Source":"System",
"ReasonCode":"SYSTEM_ERROR",
"Description":"Too Many Requests",
"Recoverable":false,
"Details":"Too many requests"
}
]
}
}
```
```json
{
"Errors":{
"Error":[
{
"Source":"Validation",
"ReasonCode":"INVALID_INPUT_FORMAT",
"Description":"Invalid characters in MerchantId",
"Recoverable":false,
"Details":"Invalid Params"
},
{
"Source":"Validation",
"ReasonCode":"MISSING_REQUIRED_INPUT",
"Description":"MerchantId can't be null or empty",
"Recoverable":false,
"Details":"Invalid Params"
},
{
"Source":"Validation",
"ReasonCode":"INVALID_INPUT_LENGTH",
"Description":"MerchantId length must be 15",
"Recoverable":false,
"Details":"Invalid Params"
}
]
}
}
```