# Code and Formats source: https://developer.mastercard.com/priceless-planet-carbon-tracker/documentation/code-and-formats/index.md ## Error Handling {#error-handling} Carbon Calculator Experience API uses standard HTTP response codes for success and failure notifications. The errors are further classified by these error types: * 200 code corresponds to success * 40X codes for a developer or user-related failures * 50X codes for Mastercard related issues ## Gateway Error Codes {#gateway-error-codes} Apart from the error codes returned by the Carbon Calculator Experience API, the Mastercard gateway returns error codes which verify 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 Experience for each error scenario that can occur: **Single Error:** ```json { "Errors": { "Error": [ { "Source": "", "ReasonCode": "", "Description": "", "Recoverable": true/false, "Details": "" } ] } } ``` **Multiple Errors:** ```json { "Errors": { "Error": [ { "Source": "", "ReasonCode": "", "Description": "", "Recoverable": true/false, "Details": "" },{ "Source": "", "ReasonCode": "", "Description": "", "Recoverable": true/false, "Details": "" } ] } } ``` | Field | Description | |-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Source** | The application that generates this error. * Every error message the gateway generates and returns has the field value as `Gateway`. * Every error message the Carbon Calculator Experience application generates has the field value as `CARBON CALCULATOR EXPERIENCE`. | | **ReasonCode** | A unique constant that the system assigns to identify the error case when you call any Carbon Calculator Experience API. For example, the API returns `INVALID_REQUEST_PARAMETER` when the request is invalid due to some missing or invalid parameters. | | **Description** | Description of the `ReasonCode` field with additional details. | | **Recoverable** | Indicates whether the API will always return this error 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 contain a link to the newly-created resource. | | 202 (ACCEPTED) | The request has been accepted for processing, but processing has not been completed or may not have started. | | 400 (BAD REQUEST) | General error when the request could not 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 perform the operation. | | 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 Experience 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 Experience Errors structure in the response. | | 5XX (SERVER ERROR) | Errors that occur in the network infrastructure between the client and the Carbon Calculator Experience server will typically result in a response code in the 500 range. These errors will never contain the Carbon Calculator Experience Errors structure in the response. | ## Carbon Calculator Experience Errors {#carbon-calculator-experience-errors} Note: The following error codes are specific to the Carbon Calculator Experience application. For errors with the `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 Experience application-specific error codes, refer to the following table. | Reason Code | Description | Recoverable | Tip to Resolve | HTTP Response Code | |----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------| | USER_NOT_FOUND | We cannot find user details for provided `userId`. Register a user through the enrollment process. | false | Your account onboarding is not yet completed. Contact your assigned Mastercard associate or send a request to [carboncalculator@mastercard.com](mailto:carboncalculator@mastercard.com) for further help. | 404 | | CRYPTO_ERROR | We are unable to decipher your request, verify your request before trying again. If the problem persists then reach out to your Mastercard associate. | 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. | 400 | | 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/priceless-planet-carbon-tracker/documentation/api-reference/index.md). | 400 | | ACCOUNT_INACTIVE | Your account is inactive, contact your Mastercard associate to activate it. Until then you will not be able to access any service. | false | Make sure your account is active or contact your assigned Mastercard associate or send a request to [carboncalculator@mastercard.com](mailto:carboncalculator@mastercard.com) for further help. | 401 | | ACCOUNT_SUSPENDED | Your account has been suspended temporarily, contact your Mastercard associate to activate it again. Until then you will not be able to access any service. | false | Register again or contact your assigned Mastercard associate or send a request to [carboncalculator@mastercard.com](mailto:carboncalculator@mastercard.com) for further help. | 401 | | ACCOUNT_TERMINATED | Your account has been terminated, you will not be able to access any service. Register yourself again. | false | Your account has been terminated, register yourself again. Contact your assigned Mastercard associate or send a request to [carboncalculator@mastercard.com](mailto:carboncalculator@mastercard.com) for further help. | 401 | | SERVICE_PROVIDER_NOT_FOUND | Service provider `clientId` is not identified. | false | Your account details cannot be found. Make sure the Client ID is present and active. Contact your Mastercard associate to activate it again or send a request to [carboncalculator@mastercard.com](mailto:carboncalculator@mastercard.com) for further help. Until then you will not be able to access any service. | 404 | | USER_INACTIVE | User is inactive, contact your Mastercard associate to activate it. Until then you will not be able to access any service. | false | Make sure the user is enrolled and active and verify that the request is valid as per [API Reference](https://developer.mastercard.com/priceless-planet-carbon-tracker/documentation/api-reference/index.md). | 401 | Note: To resolve an error, check the `Details` field in the error object. ### Sample Errors {#sample-errors} * Sample error response when `POST /issuers/users` operation contains an invalid email address. ```json { "Errors": { "Error": [ { "Source": "CARBON CALCULATOR EXPERIENCE", "ReasonCode": "INVALID_REQUEST_PARAMETER", "Description": "One of the request parameters is invalid, try again with correct request.", "Recoverable": false, "Details": "email must not be null" } ] } } ``` * Sample error response when `GET issuers/users/{userid}/dashboards` operation results user not found. ```json { "Errors": { "Error": [ { "Source": "CARBON CALCULATOR EXPERIENCE", "ReasonCode": "USER_NOT_FOUND", "Description": "We cannot find user details for provided userId. Kindly register user through the enrollment process.", "Recoverable": false, "Details": "Make sure user is enrolled through /users API endpoint." } ] } } ```