# Code and Formats source: https://developer.mastercard.com/carbon-calculator/documentation/code-and-formats/index.md ## Gateway Error Codes {#gateway-error-codes} Apart from the error codes returned by the Carbon Calculator API, error codes can be returned by the Mastercard gateway, which verifies your request's signature and routes to the correct location. For further information about 4xx/5xx response codes returned by the gateway and their possible resolutions, see [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 following structure is followed by the Carbon Calculator for each error scenario that can occur. **Single Error:** ```json { "Errors": { "Error": [ { "source": "", "description": "", "recoverable": "true/false", "details": "One of the request parameters is invalid, try again with correct request." } ] } } ``` **Multiple Errors:** ```json { "Errors": { "Error": [ { "Source": "", "ReasonCode": "", "Description": "", "Recoverable": "true/false", "Details": "" },{ "source": "", "description": "", "recoverable": "true/false", "Details": "" } ] } } ``` | Field | Description | |-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Source** | The application that generated this error. Every error message that is generated and returned by the Gateway will have this field equal to `Gateway`. If the field value is either `Service-Provider-Mgmt` or `Carbon-Calculator`, then the error is generated by the Carbon Calculator application. | | **ReasonCode** | A unique constant identifies the error case encountered when any Carbon Calculator API is called. For example, `INVALID_REQUEST_PARAMETER` is used when the request is invalid due to some missing or invalid parameters. | | **Description** | Description of the `ReasonCode` field with additional details. | | **Recoverable** | Indicates whether this error will always be returned for this request, or retrying could change the outcome. For example, if the request contains an invalid request parameter, retrying will never result in success. However, if the error is related to some unexpected timeout with the service, retrying the call could result in a successful response. | | **Details** | Provide detailed error information wherever appropriate to help in resolving errors. | ## HTTP Response codes/Reason codes {#http-response-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 Response Code | Response Description | |-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 200 (OK) | The request was completed successfully. | | 201 (CREATED) | Successful creation occurred using a POST request. The Location header will contain a link to the newly-created resource. | | 400 (BAD REQUEST) | General error when the request cannot be fulfilled due to errors such as validation errors or missing required data. | | 401 (UNAUTHORIZED) | Missing or invalid authentication token. | | 403 (FORBIDDEN) | The user is not authorized to operate. | | 404 (NOT FOUND) | The requested resource was not found. | | 405 (METHOD NOT ALLOWED) | The requested URL exists, but the requested HTTP method is not applicable. | | 500 (INTERNAL SERVER ERROR) | The Carbon Calculator server encountered an unexpected condition that prevented it from fulfilling the request. Requests resulting in a 500 response code will generally include the Carbon Calculator errors structure in the response. | | 5XX (SERVER ERROR) | Errors that occur in the network infrastructure between the client and the Carbon Calculator server will typically result in a response code in the 500 range. These errors will never contain the Carbon Calculator errors structure in the response. | For further information about the error message fields, 4xx/5xx response codes, and possible resolutions, see [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/gateway-error-codes/). ## Carbon Calculator Errors {#carbon-calculator-errors} Note: The following error codes are specific to the Carbon Calculator application. For errors with `Source` field value as, `Gateway`, refer to [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/gateway-error-codes/). For a complete list of Carbon Calculator application-specific error codes, refer to the following table. | Reason Code | Description | Recoverable | Tip to Resolve | |----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ACCOUNT_NOT_FOUND | We cannot find the account that you are using to access this service. Kindly register your account or contact your Mastercard associate if you have already registered with us earlier. | false | Your account onboarding is not yet completed. Kindly contact your assigned Mastercard associate or send a request to [carboncalculator@mastercard.com](mailto:carboncalculator@mastercard.com) for further help. | | ACCOUNT_SUSPENDED | Your account has been suspended temporarily, kindly contact your Mastercard associate to activate it again. Until then, you won't be able to access any service. | false | Kindly contact your assigned Mastercard associate or send a request to [carboncalculator@mastercard.com](mailto:carboncalculator@mastercard.com) for further help. | | CRYPTO_ERROR | Request decryption failed. | false | The encrypted payload is invalid, and the server is not able to decrypt your request. Verify that you are using the right key for payload encryption; refer to the [payload encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/) guide for more details. | | INVALID_DATE_RANGE | The requested date range is either invalid or exceeds the one-year limit. Try again with a valid date range. | false | Verify and correct the date value in the request, and then try again. | | INVALID_FPAN | The card number in the request is either invalid or does not match your currently supported account range. Try again with a valid card number or update the supported account range. | false | Verify that the PAN in the request is valid and matches your registered BIN range. If your BIN range is not yet onboarded or you want to update it on the Carbon Calculator application, then kindly contact your assigned Mastercard associate or send a request to [carboncalculator@mastercard.com](mailto:carboncalculator@mastercard.com) for further help. | | INVALID_REQUEST_PARAMETER | One of the request parameters is invalid, try again with the correct request. | false | Verify that the request is valid as per [API Reference](https://developer.mastercard.com/carbon-calculator/documentation/api-reference/index.md). | | UNSUPPORTED_MEDIA_TYPE | The requested media type is not supported, try again with the supported media type. | false | Verify and correct the `Content-Type` header value as per [API Reference](https://developer.mastercard.com/carbon-calculator/documentation/api-reference/index.md) and try again. If the problem persists then refer to [Get Help](https://developer.mastercard.com/carbon-calculator/documentation/support/index.md#get-help). | | INVALID_TRANSACTION_RECORD_ERROR | One of the transaction details such as MCC, AMOUNT or CURRENCY in the file-based scoring file is invalid or not in proper format, try again with the correct request. | false | Verify and correct the transaction values in the input file, and then try again. | | TRANSACTION_SCORING_ERROR | One of the transaction details such as MCC, AMOUNT or CURRENCY in the file-based scoring file is unsupported, try again with the correct request. | false | Verify and correct the transaction values in the input file, and then try again. | | PAYMENT_CARD_NOT_FOUND | The requested paymentCard not found for the given payment card ID in the path. | false | Verify and correct the paymentCard value in the request, and then try again. | To resolve an error, check the `Details` field in the error object. ### Sample Errors {#sample-errors} * Sample error response when `POST /transaction-footprints` operation contains invalid merchant category code (MCC): ```json { "Errors": { "Error": [ { "Source": "Carbon-Calculator", "ReasonCode": "INVALID_REQUEST_PARAMETER", "Description": "One of the request parameters is invalid, try again with correct request.", "Recoverable": false, "Details": "carbonIndexCalculation.mcTransactions[0].mcc: size must be between 1 and 4" }, { "Source": "Carbon-Calculator", "ReasonCode": "INVALID_REQUEST_PARAMETER", "Description": "One of the request parameters is invalid, try again with correct request.", "Recoverable": false, "Details": "carbonIndexCalculation.mcTransactions[0].mcc: must match \"^\\d{1,4}\"" } ] } } ``` * Sample error response when `POST /payment-cards` operation contains invalid PAN: ```json { "Errors": { "Error": [ { "Source": "Service-Provider-Mgmt", "ReasonCode": "INVALID_FPAN", "Description": "The card number in the request is either invalid or does not match with your currently supported account range. Try again with a valid card number or update the supported account range.", "Recoverable": false, "Details": "" } ] } } ``` * Sample error response when `GET /payment-cards/{payment_card_id}/transaction-footprints` operation contains invalid date range: ```json { "Errors": { "Error": [ { "Source": "Service-Provider-Mgmt", "ReasonCode": "INVALID_DATE_RANGE", "Description": "Requested date range is either invalid or exceeds the one year limit. Try again with valid a date range.", "Recoverable": false, "Details": "" } ] } } ``` * Sample error response when `POST /payment-cards/transaction-footprints/aggregates` operation contains invalid aggregate type: ```json { "Errors": { "Error": [ { "Source": "Service-Provider-Mgmt", "ReasonCode": "INVALID_REQUEST_PARAMETER", "Description": "Invalid aggregate type. Please try again with a valid value.", "Recoverable": false, "Details": "" } ] } } ``` * Sample error response when `POST /payment-cards/transaction-footprints/aggregates` operation contains invalid date range: ```json { "Errors": { "Error": [ { "Source": "Service-Provider", "ReasonCode": "INVALID_DATE_RANGE", "Description": "Requested date range is either invalid or exceeds supported limit (i.e. 26 weeks for weekly aggregate and 12 months for monthly aggregate).", "Recoverable": false, "Details": "" } ] } } ``` * Sample error response when `POST /payment-cards/transaction-footprints/aggregates` operation contains invalid date format: ```json { "Errors": { "Error": [ { "Source": "Service-Provider", "ReasonCode": "INVALID_REQUEST_PARAMETER", "Description": "One of the request parameters is invalid, try again with correct request.", "Recoverable": false, "Details": "fromDate must match \"^((?:19|20)[0-9][0-9])-(0?[1-9]|1[012])-(0?[1-9]|[12][0-9]|3[01])$\"" }, { "Source": "Service-Provider", "ReasonCode": "INVALID_REQUEST_PARAMETER", "Description": "One of the request parameters is invalid, try again with correct request.", "Recoverable": false, "Details": "toDate must match \"^((?:19|20)[0-9][0-9])-(0?[1-9]|1[012])-(0?[1-9]|[12][0-9]|3[01])$\"" } ] } } ``` * Sample error response when one of the required fields is missing for the operation `POST profiles`. ```json { "Errors": { "Error": [ { "Source": "Carbon-Calculator-Engagement-Services", "ReasonCode": "INVALID_REQUEST_PARAMETER", "Description": "One of the request parameters is invalid, try again with correct request.", "Recoverable": false, "Details": "surveyioResults.flyFrequency must be in valid format" } ] } } ``` * Sample error response when one of the required fields is missing for the operation `POST /insights`. ```json { "Errors": { "Error": [ { "Source": "Carbon-Calculator", "ReasonCode": "INVALID_REQUEST_PARAMETER", "Description": "One of the request parameters is invalid, try again with correct request.", "Recoverable": false, "Details": "profile.userAttributes must not be null" }, { "Source": "Carbon-Calculator", "ReasonCode": "INVALID_REQUEST_PARAMETER", "Description": "One of the request parameters is invalid, try again with correct request.", "Recoverable": false, "Details": "profile.traits must not be null" } ] } } ``` * Sample error response when one or more request parameters is either missing or is invalid for the operation `GET /insights`. ```json { "Errors": { "Error": [ { "Source": "Carbon-Calculator-Engagement-Services", "ReasonCode": "LANGUAGE_NOT_FOUND", "Description": "Unsupported language or branding", "Recoverable": false, "Details": "" } ] } } ```