# Codes and Formats source: https://developer.mastercard.com/commercial-event-notifications/documentation/codeandformats/index.md This API uses standard HTTP response codes to indicate success or failure, and a `ReasonCode` to classify errors. 2XX status codes represent success, 4XX status codes represent developer or user-related failures, and 5XX status codes represent issues related to Mastercard. ## HTTP Status Response Code {#http-status-response-code} The following table provides a list of HTTP status codes that you receive in response to your request from the API. | Status | Response | Description | |--------|------------------------|--------------------------------------------------------------------------------------------| | 200 | OK | The request has succeeded. | | 201 | CREATED | The new resource has been created successfully either through POST or PUT requests. | | 202 | ACCEPTED | The server has received the request but has yet to act on it. | | 204 | NO CONTENT | The server has no content to send for a request. | | 400 | BAD REQUEST | The server cannot process the request if something is not right in your request. | | 401 | UNAUTHORIZED | The client does not have access to the resource. | | 402 | REQUEST FAILED | The parameters were valid but the request failed. | | 403 | FORBIDDEN | The client permanently has no access to the resource. | | 404 | NOT FOUND | The requested resource cannot be found. | | 405 | METHOD NOT ALLOWED | The target resource does not support the requested method. | | 406 | NOT ACCEPTABLE | The server does not implement the media type that would be acceptable to the client. | | 409 | CONFLICT | The request conflicts with another request (perhaps due to using the same idempotent key). | | 415 | UNSUPPORTED MEDIA TYPE | The server does not support the request payload's media type. | | 422 | UNPROCESSABLE ENTITY | The API cannot complete the requested action due to semantic errors. | | 429 | TOO MANY REQUESTS | The user has sent too many requests in a given amount of time. | | 500 | SERVER ERRORS | The server cannot complete the request due to an unexpected error. | ## Handling Gateway Errors {#handling-gateway-errors} Mastercard API Gateway returns errors due to a communication, authentication, or request structure error. To solve these errors, refer to the [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/gateway-error-codes/) topic. ## Error Structure {#error-structure} When a request fails, the API returns the following structure with details about each error: ```bash { "Errors": { "Error": [ { "Source": "", "ReasonCode": "", "Description": "", "Recoverable": true/false, "Details": "" } ] } } ``` Where, * **Source** - The source of the error, which is either the Mastercard gateway or the event notifications API. * **ReasonCode** - A code to identify the error situation. * **Description** - Explains why your request failed. * **Recoverable** - Whether resending the same request later can succeed. `true` for system outages or unexpected timeouts. `false` for errors that you must correct before you resend the request. * **Details** - Additional details regarding an error. ## Application Error Codes {#application-error-codes} If a request fails because of incorrect request parameters, the API returns one or more of the following error codes and details. Correct the parameters and resend the request. | Reason Code | Description | Details | Resolution Steps | |----------------------------------------------|----------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------| | resource.not.found | The specified resource was not found. | | Set the correct resource (virtual card number, real card number, contact details or funding source etc.). | | format.invalid | One or more fields has an invalid format. | The field 'subjectType' has an invalid format. | Set the 'subjectType' to a valid format. | | user.authentication.absent | No authentication data available for the user. | | Set user credentials. | | subscriber.not.allowed | Access is not allowed. | Subscriber with consumerKey 'INACTIVE_SUBSCRIBER' does not have permissions to complete the request. | Set the correct consumerKey. | | invalid.data | One or more fields contain invalid data. | subjectType' must not be null. | Provide a valid subjectType. | | subscriber.webhook.path.already.registered | This subscriber webhook path is already registered. | | Provide a unique webhook path. | | format.invalid | One or more fields has an invalid format. | The 'subscriptionBoundaries' field has an invalid format. | Set subscriptionBoundaries in a valid format. | | format.invalid | The 'entityType' field has an invalid format. | | Set entityType in a valid format. | | subscriber.invalid | Invalid subscriber. | Subject boundary is not set. | Set the subject boundary. | | subscriber.invalid | Invalid subscriber. | Subscription boundary is not set. | Set the subscription boundary. | | user.authorization.missing | No authorization data available for the user or the session. | | Set user authorization privileges. | | invalid.data | One or more fields contain invalid data. | 'subjectType' must not be null. | Provide a valid subjectType. | | subscriber.consumer.key.already.registered | This consumer key is already registered. | | Provide a unique consumer key. | | subscriber.invalid | Invalid subscriber. | Subscription is not allowed during Subscriber creation. | Subscriptions can only be created after the subscriber is created. Please create the subscriber successfully before creating the subscription. | | subscriber.invalid | Invalid subscriber. | Duplicate subscription boundaries are set. | Provide unique subscription boundaries. | | length.short | Invalid field. | The 'consumerKey' parameter has an invalid length. | Set the correct consumerKey. | | invalid.data | One or more fields contain invalid data. | The 'consumerKey' parameter must not be null. | Set the correct consumerKey. | | field.required | Invalid field. | The 'active' field is missing. | Set the missing field. | | invalid.data | One or more fields contain invalid data. | The 'name' field must contain only letters, numbers, dashes, and underscores. | Set the correct name. | | subscription.invalid.specification.type | The 'specification type' field has an invalid 'THIS_SPECIFICATION_ TYPE_IS_INVALID' value. | | Provide the correct value for the specification type. | | subscription.invalid.specification.operator | Invalid specification. | The first specification must use the WHERE operator. | Provide the correct value for the specification operator. | | subscription.incorrect.value.for.field | Invalid card number value. | Invalid card number range: "value" must be less than "anotherValue". | Provide the correct value for the card number. | | subscription.invalid.field.mapping.reference | Field mapping error. | Cannot find field mapping, fieldMappingNotAvailableToPublic. | Check and provide the correct field mapping. | | subscriber.not.allowed | Access is not allowed. | Subscriber with consumerKey 'INVALID_CONSUMER_KEY' does not have permissions to complete the request. | Set the correct consumerKey or check for permissions available on the consumerKey. | | subscriber.invalid | Invalid subscriber. | Subscription boundary is not set. | Set the subscription boundary. | | subscription.invalid.specification.operator | Invalid specification. | WHERE operator should be used in the first specification, other specifications should use only AND or OR operators. | Use the correct specification operator. | | subscriber.invalid | Invalid subscriber. | Subject boundary is not set. | Set the subject boundary. | | subscription.unsupported.operator.for.field | Unsupported operator for field. | GREATER_THAN operator does not apply to TEXT. | Use the correct specification operator. | | subscription.expected.content.invalid.value | One or more fields is invalid. | 'InvalidCurrency' should be a currency. | Set the correct type. | | length.long | Invalid field. | The 'name' parameter has an invalid length. | Set the correct field length. | | subscription.name.already.registered | This subscription name is already registered for this subscriber. | | Provide a unique subscription name. | | format.invalid | One or more fields has an invalid format. | The 'specifications' field has an invalid format. | Provide a valid value for specifications. | | format.invalid | One or more fields has an invalid format. | The 'expectedContent' field has an invalid format. | Provide a valid value for expectedContent. | | format.invalid | One or more fields has an invalid format. | The 'contentType' field has an invalid format. | Provide a valid value for contentType. | | subscription.content.type.mismatch | Content type mismatch. | The field mapping realPaymentCard.field.number (TEXT) does not match the content type of the field (DECIMAL). | Provide a valid type for content. | | resource.not.found | The specified resource was not found. | | Provide a different value. | | format.invalid | One or more fields has an invalid format. | The 'subjectType' field has an invalid format. | Provide a valid value for subjectType. | | subscription.unsupported.operator.for.field | Unsupported operator for field. | BETWEEN an operator does not apply to TEXT. | Use the correct specification operator. | | field.required | Invalid field. | The 'specifications\[0\].fieldOperator' field is missing. | Set the missing field. | | field.required | Invalid field. | "Field" cannot be null. | Set the missing field. | | subscription.expected.content.invalid.value | One or more fields is invalid. | '1.0.0.0' should be a decimal. | Provide the correct type. | | subscription.incorrect.value.for.field | Invalid card number value. | Card number must be between 12 and 19 digits. | Provide a valid card number. | | subscription.expected.content.invalid.value | One or more fields is invalid. | | Set the field in a valid format. | | subscription.invalid.specification.operator | Invalid specification. | WHERE an operator should be used in the first specification, other specifications should use only AND or OR operators. | Use the correct specification operator. | | subscription.incorrect.value.for.field | Invalid card number value. | Card number must be between 12 and 19 digits. | Provide a valid card number. | | format.invalid | One or more fields has an invalid format. | The 'specifications' field has an invalid format. | Provide the correct specifications format. | | format.invalid | One or more fields has an invalid format. | The 'operator' field has an invalid format. | Use the correct specification operator. | | subscriber.not.allowed | Access is not allowed. | Subscriber with consumerKey 'MC_API_CONSUMER _KEY_INVALID' does not have permissions to complete the request. | Set the correct consumerKey. | | format.invalid | One or more fields has an invalid format. | The 'specifications' field has an invalid format. | Provide the correct specifications format. | | format.invalid | One or more fields has an invalid format. | The 'fieldOperator' field has an invalid format. | Provide the correct fieldOperator format. | | invalid.data | One or more fields contain invalid data. | The 'name' field must contain only letters, numbers, dashes, and underscores. | Set the correct name. | | subscription.expected.content.invalid.value | One or more fields is invalid. | 'InvalidDate' should be a date. | Set the correct date format. | | invalid.data | One or more fields contain invalid data. | The 'value' field must only contain letters, digits, spaces, hyphens, slashes, commas, periods, and underscores. | Set the correct value. | | subscription.unsupported.operator.for.field | Unsupported operator for field. | BETWEEN operator does not apply to TEXT. | Use the correct specification operator. | | field.required | Invalid field. | The 'specifications\[0\]. fieldMappingName' field is missing. | Set the missing field. | | parameter.invalid | No property 'invalid' found for type 'Subscription'. | | Set the correct property for the Subscription. | | parameter.offset.invalid | Offset parameter validation error. | Pagination offset must be greater than or equal to 0. | Set the correct pagination offset. | | parameter.offset.invalid | Offset parameter validation error. | Offset should not be greater than or equal to the total number of records (total). | | | parameter.pageLength.invalid | Content type mismatch. | The 'PageLength' parameter should be type integer. | Set the correct field length. | | server.error | Internal server error. | | | | parameter.pageNumber.invalid | Page number parameter validation error. | Page number should be greater than 0. | Set a page number greater than 0. | | subscription.incorrect.value.for.operator | Operator is invalid. | BETWEEN the operator requires two values. | Use the correct specification operator. | | subscription.incorrect.value.for.operator | Operator is invalid. | EQUALS, LESS_THAN and GREATER_THAN operators must have a single value. | Use the correct specification operator. | | subscription.subject.type.mismatch | The following field mappings do not match the subscription subject type: 'field-mapping-02'. | | Check and provide the correct field mapping. | | user.not.authorized | No authorization data available for the user or the session. | | Set user authorization privileges. | | parameter.start.missing | The start parameter is required but was not provided. | | Start parameter is required. Specify the start parameter. | | parameter.end.missing | The end parameter is required but was not provided. | | End parameter is required. Specify the end parameter. | | field.invalid | One or more fields contain invalid data. | Invalid push status: INVALID. | Provide a valid push status. | | date.range.invalid | Invalid Date Range. | Start date must be earlier than end date. | Set the correct date range. | | date.format.invalid | Invalid Date Format. | End date must be in the past. | Set the correct date format. | | parameter.limit.invalid | Limit parameter validation error. | Pagination limit should be between 1 and 100. | Set the pagination limit between 1 and 100. | | parameter.limit.type.mismatch | Content type mismatch. | Limit parameter should be integer. | Set the correct type for the limit. | | user.authentication.absent | No authentication data is available for the user. | | Set user credentials. | | user.authorization.missing | No authorization data available for the user or the session. | | Set user authorization privileges. | | user.not.authorized | No authorization data available for the user or the session. | | Set user authorization privileges. | | session.commonSessionId.missing | The commonSessionId is not set. | | Set the commonSessionId. | | field.invalid | One or more fields contain invalid data. | Invalid subject type. | Provide a valid subjectType. | ## In Control On-behalf Service Result Code {#in-control-on-behalf-service-result-code} | Code | Description | |-------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 17 = In Control Virtual Card Service | A = Virtual Card Number (expiration date does not match) B = Virtual Card Number (expiration date expired) C = Virtual Card Number Virtual CVC 2 does not match D = In Control Validity Period Limit E = In Control Transaction Amount Limit Check F = In Control Cumulative Amount Limit Check G = In Control Transaction Number Usage H = In Control Merchant ID Limit I = In Control Invalid Virtual Card Number---Real Card Number mapping relationship J = In Control MCC Limit K = In Control Database Status Bad L = In Control Geographic Restriction M = In Control Transaction Type Restriction P = In Control Transaction Time/Date Restriction U = Unable to process V = Valid | | 18 = Fraud Scoring Service | C = Fraud Scoring Service was performed successfully U = Fraud Scoring Service was not performed successfully | | 20 = In Control RCN Spend Control Service | D = In Control Validity Period Limit E = In Control Transaction Amount Limit Check F = In Control Cumulative Amount Limit Check G = In Control Transaction Number Usage H = In Control Merchant ID Limit J = In Control MCC Limit K = In Control Database Status Bad L = In Control Geographic Restriction M = In Control Transaction Type Restriction P = In Control Transaction Time/Date Restriction U = Unable to process V = Valid | ## Next Steps {#next-steps} * Refer to [Integration and Testing](https://developer.mastercard.com/commercial-event-notifications/documentation/integration-and-testing/index.md) for request scenarios. * Consult the [API Reference](https://developer.mastercard.com/commercial-event-notifications/documentation/parameters/index.md) for complete endpoint specifications, request and response schemas, and environment URLs. * If you run into issues, visit [Support](https://developer.mastercard.com/commercial-event-notifications/documentation/support/index.md) for FAQs and troubleshooting guidance.