# Code and Formats source: https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/code-and-formats/index.md ## HTTP Status Codes/Reason Codes {#http-status-codesreason-codes} Resource requests use HTTP response codes to provide a coarse-grain indication of the result of each request. The most common expected response codes for the supported HTTP methods are as follows: | **HTTP Status Code** | **Reason Code** | **Description** | **Resolution** | |--------------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 200 (OK) | N/A | The request was completed successfully. | No action needed --- request processed successfully. | | 204 (NO CONTENT) | N/A | The server successfully processed the request and is not returning any content. | No action needed --- resource updated successfully. | | 400 (BAD REQUEST) | BAD_REQUEST | General error when the request could not be fulfilled due to errors such as validation errors or missing required data. | Validate request parameters, check required fields, and ensure proper data formats before retrying. | | 401 (UNAUTHORIZED) | UNAUTHORIZED | The mTLS client certificate or credentials could not be validated. | Verify the client certificate, private key, certificate chain, and project authorization. See [API Basics](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/api-basics/index.md) for mTLS configuration. | | 403 (FORBIDDEN) | PERMISSION_DENIED | The API key does not have permissions to perform the request. | Contact your administrator to verify permissions or use an API key with appropriate access rights. | | 404 (RESOURCE NOT FOUND) | NOT_FOUND | The requested resource was not found. | Verify the resource URL is correct and the resource exists. Check for typos in the endpoint path. | | 405 (METHOD NOT ALLOWED) | N/A | The server does not implement the requested HTTP method. | Check the API Reference to confirm the correct HTTP method for the endpoint and update your request accordingly. | ## Gateway Error Codes {#gateway-error-codes} In addition to service error codes, error codes can also be returned by Mastercard's gateway, which is used to verify your request's signature, and route it to the correct location. You can find a list of the errors returned by our Gateway, as well as resolutions to each errors, on [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/security-and-authentication/gateway-error-codes/). ## Error Structure {#error-structure} To ensure a consistent experience across all Mastercard APIs, the Benefit Allocation Service API follows the structure below for each error scenario that can occur. **Single error:** ```json { "Errors": { "Error": [ { "Source": "Benefits Personalization", "ReasonCode": "", "Description": "", "Recoverable": "" } ] } } ``` **Multiple errors:** ```json { "Errors": { "Error": [ { "Source": "Benefits Personalization", "ReasonCode": "", "Description": "", "Recoverable": "" }, { "Source": "Benefits Personalization", "ReasonCode": "", "Description": "", "Recoverable": "" } ] } } ``` | **Field** | **Description** | |-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Source | The application that generated this error. Errors returned by the Mastercard gateway will have this set to `Gateway`. Errors generated by the Benefit Allocation Service will have this set to `Benefits Personalization`. | | ReasonCode | A unique code identifying the specific error case encountered. See [Service Error Codes](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/code-and-formats/index.md#service-error-codes) for the full list. | | Description | A description of the `ReasonCode` providing additional detail about what caused the error. | | Recoverable | Indicates whether retrying the request could produce a different outcome. `false` means the error will persist until the request is corrected. `true` means a transient issue occurred and a retry may succeed (see reason code `40099909`). | ## Service Error Codes {#service-error-codes} Error codes specific to Benefit Allocation Service API are listed below. Warning: **Addressing errors:** If any of these codes are received in response to a request please do not retry without addressing the issue, incorrect information was submitted and the response will not change between requests. If a request receives a success response, no further calls should occur. | **Error or Reason Code** | **Description** | **How to Resolve** | |--------------------------|-----------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 7 | The account range associated to the PAN is invalid for the ICA. | Do not retry, instantly check if this should be sent to Mastercard based on contracts, check with the Customer business team. If necessary, escalate to Mastercard's CTS team to research further. | | 8 | Segment is not eligible for ICA listed | Provide Valid segment associated to ICA | | 9 | The effective date of set assignment for the PAN is outside the valid date range of the segment effective date. | Provide valid effective date | | 12 | Cardholder can only have one active segment. | PAN has an active segment, to change segment please cancel the active segment and assign a new one or replace the active segment | | 37 | Required field missing, Card Number. | Provide a card number. | | 39 | Required field missing, Segment Code. | Provide Segment Code | | 40 | Required field missing, Effective Date. | Provide Effective Date | | 43 | Card has no segment assigned / Card has no available account | Enter a valid Card Number and segment. After a success message is received, no further calls should occur. If a duplicate request is received one of these errors will be generated and no further retries should occur. | | 45 | No fixed bundle found for ICA and segment code | Enter a valid Segment Code associated to the ICA | | 46 | New PAN is already in use. | Enter a valid destination PAN on replace. After a success message is received, no further calls should occur. If a duplicate request is received one of these errors will be generated and no further retries should occur. | | 47 | Required field missing, New Pan. | Enter a valid destination PAN for replace | | 48 | Expiry date can not be before effective date. | Enter a valid expiry date which is after the effective date. If cancelling and re-assigning a segment, the effective date has to be after the cancel date, as the benefit runs through the full day. | | 49 | Required field missing, Expiry Date. | Provide a Expiry Date | | 50 | Required field missing, Api key. | Provide API Key | | 51 | Not authorized to allocate benefits for given card number | Provide Valid API Key which is authorized for the card | | 52 | Only one segment is allowed | Enter only one segment in the input request | | 54 | Invalid format on field: | Fix the format of the mentioned field | | 55 | Required field missing, Is Frozen | Provide the boolean for Is Frozen | | 56 | Required field missing, date | Provide a Date | | 57 | Invalid encryption key used. Please re-try with the correct key | Provide a valid encryption key | | 58 | Signature verification failed | Make sure that you are signing the encrypted payload with the correct signing key | | 59 | Invalid signing key used. Please re-try with the correct key | Provide a valid signing key | | 62 | Invalid bundle code | Provide a valid bundle code associated to the ICA. | | 64 | Bundle not assigned to this card | Verify the bundle code is currently assigned to the card before attempting to cancel, replace, or update it. | | 69 | Duplicate bundle code with conflicting expiry dates | A bundle code appears more than once in the request with different expiry dates. Ensure each bundle code appears only once per request. | | 72 | Bundle already cancelled | The bundle has already been cancelled. No further action is needed. | | 74 | Cannot move effective date before the current active effective date. | The expiry date provided is in the past. Provide a current or future expiry date. | | 40099909 | Some error occurred while invoking the downstream system | This is the only instance in which a request needs to be retried. | ### Error Code to Endpoint Reference {#error-code-to-endpoint-reference} The following table maps each service error code to the API endpoint(s) that can return it. | **Error or Reason Code** | **Applicable Endpoints** | |--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 7 | All endpoints | | 8 | `POST /card-segments`, `PUT /card-segments-replacements` | | 9 | `POST /card-segments`, `PUT /card-segments-replacements`, `PUT /card-segments-cancellations` | | 12 | `POST /card-segments` | | 37 | All endpoints | | 39 | `POST /card-segments`, `PUT /card-segments-replacements`, `PUT /card-segments-cancellations` | | 40 | `POST /card-segments`, `PUT /card-segments-replacements`, `POST /cards`, `POST /card-bundles`, `PUT /card-bundles-updates` | | 43 | `POST /card-segments`, `PUT /card-segments-replacements`, `PUT /card-segments-cancellations`, `POST /cards`, `PUT /cards`, `PUT /card-bundles-cancellations`, `PUT /card-bundles-replacements`, `PUT /card-bundles-updates` | | 45 | `POST /card-segments`, `PUT /card-segments-replacements` | | 46 | `POST /cards` | | 47 | `POST /cards` | | 48 | `POST /card-segments`, `PUT /card-segments-replacements`, `PUT /card-segments-cancellations`, `POST /card-bundles`, `PUT /card-bundles-cancellations`, `PUT /card-bundles-updates` | | 49 | `PUT /card-segments-cancellations`, `POST /card-bundles`, `PUT /card-bundles-cancellations` | | 50 | All endpoints | | 51 | All endpoints | | 52 | `POST /card-segments` | | 54 | All endpoints | | 55 | `PUT /cards` | | 56 | `POST /card-segments`, `POST /cards`, `POST /card-bundles`, `PUT /card-bundles-updates` | | 57 | All encrypted endpoints | | 58 | All endpoints | | 59 | All endpoints | | 62 | `POST /card-bundles`, `PUT /card-bundles-cancellations`, `PUT /card-bundles-replacements`, `PUT /card-bundles-updates` | | 64 | `PUT /card-bundles-cancellations`, `PUT /card-bundles-replacements`, `PUT /card-bundles-updates` | | 69 | `POST /card-bundles`, `PUT /card-bundles-cancellations`, `PUT /card-bundles-replacements`, `PUT /card-bundles-updates` | | 72 | `PUT /card-bundles-cancellations` | | 74 | `PUT /card-bundles-cancellations`, `PUT /card-bundles-updates` | | 40099909 | All endpoints | ## Sample Errors {#sample-errors} The following are representative error responses returned by the Benefit Allocation Service API for common failure scenarios. * Sample `400` error response from `POST /card-segments` when the request is missing the required `effectiveDate` field: ```json { "Errors": { "Error": [ { "Source": "Benefits Personalization", "ReasonCode": "40", "Description": "Required field missing, Effective Date.", "Recoverable": false } ] } } ``` * Sample `400` error response from `POST /card-segments` when the segment code is not eligible for the ICA: ```json { "Errors": { "Error": [ { "Source": "Benefits Personalization", "ReasonCode": "8", "Description": "Segment is not eligible for ICA listed.", "Recoverable": false } ] } } ``` * Sample `400` error response from `PUT /cards` when the required `isFrozen` field is missing from the request: ```json { "Errors": { "Error": [ { "Source": "Benefits Personalization", "ReasonCode": "55", "Description": "Required field missing, Is Frozen.", "Recoverable": false } ] } } ``` * Sample `401` error response from any endpoint when the request signature cannot be verified: ```json { "Errors": { "Error": [ { "Source": "Benefits Personalization", "ReasonCode": "58", "Description": "Signature verification failed.", "Recoverable": false } ] } } ``` * Sample `400` error response from any endpoint when an unexpected downstream error occurs (the only scenario where a retry is appropriate): ```json { "Errors": { "Error": [ { "Source": "Benefits Personalization", "ReasonCode": "40099909", "Description": "Some error occurred while invoking the downstream system.", "Recoverable": true } ] } } ``` ## General Troubleshooting Tips {#general-troubleshooting-tips} 1. **Validate Request Format**: Ensure JSON payloads are properly formatted and contain all required fields. Use a JSON validator to check syntax before sending requests. 2. **Enable Comprehensive Logging**: Log both request and response details, including headers, timestamps, and correlation IDs for effective debugging. 3. **Monitor API Usage**: Track your API call volume to stay within rate limits and identify usage patterns that might cause issues. 4. **Contact Support**: For persistent issues, contact our technical support team and include: * Correlation ID (found in response headers) * Exact timestamp of the error (including timezone) * Complete error response payload * Detailed steps to reproduce the issue * Your environment details (MTF or Production) ## Additional Resources {#additional-resources} * [API Documentation](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/api-reference/index.md) * [Authentication Guide](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-mtls-to-access-mastercard-apis/) * [Payload Encryption Guide](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/) * [Support](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/support/index.md)