# Code and Formats source: https://developer.mastercard.com/merchant-self-services/documentation/code-and-formats/index.md ## Error Codes {#error-codes} ### Error Structure {#error-structure} The Merchant Self Services API returns errors in the following structure. ```json { "Errors": { "Error": [ { "Source": "", "ReasonCode": "", "Description": "", "Recoverable": true, "Details": "" } ] } } ``` Use `ReasonCode`, `Description`, and `Details` together to identify the affected request value. The `Recoverable` value indicates whether retrying the request could change the outcome. Correct request data or configuration errors before retrying. ## HTTP Response Status Codes {#http-response-status-codes} | Status code | Response | Description | |-------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `200` | OK | The request succeeded and the response includes a payload. | | `400` | BAD REQUEST | The request contains an error, such as invalid request data, a malformed body, a missing header, or an invalid parameter. See [400 Bad Request](https://developer.mastercard.com/merchant-self-services/documentation/code-and-formats/index.md#400-bad-request) for API-specific reason codes and recovery guidance. | | `401` | UNAUTHORIZED | The authentication token is missing or invalid. This response can also indicate that the client ID does not correspond to a member in the system. | | `403` | FORBIDDEN | The caller is not authorized to perform the operation, or the requested resource does not belong to the member. | | `404` | NOT FOUND | The requested endpoint or resource could not be found. | | `405` | METHOD NOT ALLOWED | The HTTP method, such as `POST`, `PUT`, `GET`, or `DELETE`, is not supported for the requested resource. | | `415` | UNSUPPORTED MEDIA TYPE | The server does not support the request payload's media type. | | `422` | UNPROCESSABLE ENTITY | The server understands the content type and syntax, but cannot process the request because of validation or business-rule errors. | | `429` | TOO MANY REQUESTS | Too many requests reached the API in a short period. | ## API-Specific Error Codes {#api-specific-error-codes} ### 400 Bad Request {#400-bad-request} A `400 Bad Request` response indicates that the Merchant Self Services API cannot process the request because one or more request inputs are invalid or missing. The response can include multiple error objects. Review and resolve each error before resubmitting the request. | Reason code | Description | Common endpoint or workflow context | How to resolve | |-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `InvalidData` | One or more fields fail validation. The API returns an error for each invalid field. | Create or update workflows that submit merchant, sub-merchant, location, card acceptor, descriptor, logo, or configuration data. | Review `Description` and `Details` for the field identified by each error. Compare its value with the field requirements in the [API Reference](https://developer.mastercard.com/merchant-self-services/documentation/api-reference/index.md), including required status, length, allowed values, and format. Correct every reported field and resubmit the request. | | `InvalidParameterSet` | The request body is missing or malformed. | `POST` or `PUT` operations that require a JSON request body. | Confirm that a request body is present, is valid JSON, and uses the schema documented for the operation in the [API Reference](https://developer.mastercard.com/merchant-self-services/documentation/api-reference/index.md). Verify the object and array structure, field names, commas, quotation marks, and braces before resubmitting. | | `FormatInvalid` | A field value cannot be parsed as the expected data type or format. For example, a string might be supplied where an integer is expected. | Create or update workflows that include typed values such as integers, dates, UUIDs, country codes, or enumerated values. | Use `Description` and `Details` to identify the affected field. Check its type and format in the [API Reference](https://developer.mastercard.com/merchant-self-services/documentation/api-reference/index.md). Correct the value without changing unrelated fields, then resubmit the request. | | `MissingRequiredHeader` | A required request header is missing or null. | Any operation that requires request metadata such as `User-Id`, `Submitter-First-Name`, or `Submitter-Last-Name`. Update operations can also require `If-Match`. | Identify the missing header from `Description` or `Details`. Add the header with a non-null value. For `If-Match`, first retrieve the resource and use the latest `Etag` response-header value. Re-sign the request after changing its headers, then resend it. | | `ParameterInvalid` | A path or query parameter is invalid or has the wrong format. | Retrieve, update, delete, search, and pagination workflows that pass a resource identifier in the path or filtering, sorting, paging, or configuration values in the query string. | Identify the parameter in `Description` or `Details`. Verify its name, location, type, format, and allowed values against the endpoint definition in the [API Reference](https://developer.mastercard.com/merchant-self-services/documentation/api-reference/index.md). If it is a resource identifier, use the value returned by the corresponding create or retrieve operation. Correct the request URL, re-sign the request, and retry. | | `QueryStringMissing` | A required query-string parameter is missing. | Operations that require a query parameter to identify, filter, or act on a resource or configuration. | Identify the required parameter in `Description` or `Details`. Add it to the query string using the exact name documented in the [API Reference](https://developer.mastercard.com/merchant-self-services/documentation/api-reference/index.md), URL-encode the value when required, re-sign the complete request URL, and resend the request. | ### Troubleshoot API-specific errors {#troubleshoot-api-specific-errors} Use this sequence for API-specific reason codes: 1. Check the HTTP status and review every object in the `Errors.Error` array. 2. Use `ReasonCode` to select the applicable recovery guidance in the table above. 3. Use `Description` and `Details` to identify the exact header, path parameter, query parameter, or request-body field involved. 4. Compare the request with the operation definition and schema in the [API Reference](https://developer.mastercard.com/merchant-self-services/documentation/api-reference/index.md). 5. Correct the request. If you change the HTTP method, URL, query string, body, or signed headers, generate a new OAuth signature before retrying. 6. Run the applicable validation checks in [Testing](https://developer.mastercard.com/merchant-self-services/documentation/testing/index.md) after the corrected request succeeds. For project credentials and a first Sandbox connectivity check, see the [Quick Start Guide](https://developer.mastercard.com/merchant-self-services/documentation/tutorials-and-guides/quick-start-guide/index.md). For a complete Java signing and request example, see the [Reference Application Tutorial](https://developer.mastercard.com/merchant-self-services/documentation/tutorials-and-guides/reference-app-tutorial/index.md). ## Gateway Errors {#gateway-errors} Gateway-layer errors cover platform concerns such as authentication, authorization, request signing, throttling, and other `4xx` or `5xx` responses generated before or outside Merchant Self Services application processing. For the authoritative gateway reason codes and recovery guidance, see [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/security-and-authentication/gateway-error-codes/).