# Code and Formats source: https://developer.mastercard.com/small-business-credit-analytics/documentation/code-and-formats/index.md ## Error Handling {#error-handling} Small Business Credit Analytics API uses standard HTTP response codes for success and failure notifications. The errors are further classified by error type as follows: * 200 code corresponds to success * 40X codes for a developer or user-related failures * 50X codes for Mastercard related issues For the full error response schema and examples, see the [API Reference](https://developer.mastercard.com/small-business-credit-analytics/documentation/api-reference/index.md) or download the [OpenAPI specification](https://static.developer.mastercard.com/content/small-business-credit-analytics/swagger/swagger.yaml). ## Gateway Error Codes {#gateway-error-codes} Apart from the error codes returned by the Small Business Credit Analytics 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 Small Business Credit Analytics for each error scenario that can occur. **Single Error: country_code** ```json { "Errors": { "Error": [ { "Source": "CreditAnalytics", "ReasonCode": "INVALID_DATA: country_code", "Description": "Validation failed for country_code parameter", "Recoverable": false, "Details": "An invalid value was provided in for country_code. country_code must match ^[A-Z]+ and be a 3-letter country abbreviation, following the ISO Country Codes standard. Only currently supported countries are accepted." } ] } } ``` **Matches Single Error: id_type** ```json { "Errors": { "Error": [ { "Source": "CreditAnalytics", "ReasonCode": "INVALID_DATA: id_type", "Description": "Validation failed for id_type parameter", "Recoverable": false, "Details": "An invalid value was entered for id_type. Currently SBCA supports only MERCHANT_ID" } ] } } ``` **Metrics Single Error: location_id** ```json { "Errors": { "Error": [ { "Source": "CreditAnalytics", "ReasonCode": "INVALID_DATA: location_id", "Description": "Validation failed for location_id parameter", "Recoverable": false, "Details": "An invalid value was entered for location_id - Location ID should follow the following format '123e4567-e89b-12d3-a456-426614174000'." } ] } } ``` | 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 `CreditAnalytics`, then the error is generated by the Small Business Credit Analytics (SBCA) application. | | **ReasonCode** | A unique constant identifying the error case encountered when Small Business Credit Analytics (SBCA) API is called. For example, `INVALID_DATA:has_consent` 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. | ## SBCA API Errors {#sbca-api-errors} ### Matches Errors {#matches-errors} The following errors occur at `GET /matches` --- see the [API Reference](https://developer.mastercard.com/small-business-credit-analytics/documentation/api-reference/index.md) for endpoint details. | Response Code | Reason Code | Description | Tip to Resolve | |:--------------|:---------------------------|:-----------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 403 | COUNTRY_NOT_PERMITTED | No Permission to access merchant information for the requested country_code. | Access to merchant data for this country is not permitted under your current agreement. To request access, please contact your Mastercard representative. Refer [API Basics --- Environments](https://developer.mastercard.com/small-business-credit-analytics/documentation/api-basics/index.md#environments) for your current setup. | | 403 | AGG_MERCHANT_NOT_PERMITTED | No permission to retrieve the match for the aggregated merchant | Merchant you are trying to search for is an aggregated merchant. SBCA only works with small and medium businesses. Please provide the non-aggregated merchant data to receive a match. | | 404 | MATCHES_NOT_FOUND | No potential matches found | Check with the merchant for alternative values for the company name, address, and other similar values. Refer [Merchant Match test cases](https://developer.mastercard.com/small-business-credit-analytics/documentation/testing/merchant-match/index.md) for valid test inputs. | ### Metrics Errors {#metrics-errors} The following errors occur at `GET /metrics/{location_id}` --- [Step 2 of the Retail Sales Analytics flow](https://developer.mastercard.com/small-business-credit-analytics/documentation/use-cases/retail-sales-analytics/index.md#2-retail-sales-analytics-metrics) or [Retail Sales Benchmarks flow](https://developer.mastercard.com/small-business-credit-analytics/documentation/use-cases/retail-sales-benchmarks/index.md#2-retail-sales-benchmarks-metrics). | Response Code | Reason Code | Description | Tip to Resolve | |:--------------|:----------------------|:----------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 403 | CONSENT_NOT_PROVIDED | has_consent parameter was set to 'false' | Consent from the merchant is required in order to access performance metrics for said merchant. Set `has_consent=true` only after obtaining consent from the merchant as outlined in the [pre-requisites](https://developer.mastercard.com/small-business-credit-analytics/documentation/use-cases/retail-sales-analytics/index.md#pre-requisites). | | 403 | ACCESS_FORBIDDEN | No permission to access Retail Sales Benchmarks | Ensure that you have permission for Retail Sales Benchmarks. | | 404 | LOCATION_NOT_FOUND | No matched merchant found | Often this is due to Mastercard ongoing reconciliation processes - try calling the matches API again with the original merchant details to get a new location ID. | | 404 | METRICS_NOT_FOUND | No potential metrics found for the provided merchant information | Try calling the metrics API again in a few days in case this is resolved by Mastercard's ongoing reconciliation processes or processing additional transactions for this merchant. | | 403 | COUNTRY_NOT_PERMITTED | No Permission to access merchant information for the requested location_id. | Access to merchant data for this location_id is not permitted under your current agreement. To request access, please contact your Mastercard representative. | ### Common Errors {#common-errors} The following errors can occur on any SBCA endpoint (`GET /matches` or `GET /metrics/{location_id}`). | Response Code | Reason Code | Description | Tip to Resolve | |:--------------|:--------------------------------------|:---------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 400 | INVALID_OATH_CONSUMER_KEY | Consumer key must be 97 characters long, split by an exclamation mark symbol. Received: `length` | Re-download your `.p12` file from the [Developer Dashboard](https://developer.mastercard.com/dashboard) and verify the consumer key format. See [API Basics --- Client Authentication](https://developer.mastercard.com/small-business-credit-analytics/documentation/api-basics/index.md#client-authentication). | | 400 | QUERYSTRING.\.MISSING | The \ `querystring` parameter is required but not provided | Add the missing parameter. Refer to the [API Reference](https://developer.mastercard.com/small-business-credit-analytics/documentation/api-reference/index.md) for required parameters per endpoint. | | 400 | INVALID_DATA:\ | Validation failed for \ | Pass a valid value. Check the `Details` field in the error response for the exact validation rule. See the [API Reference](https://developer.mastercard.com/small-business-credit-analytics/documentation/api-reference/index.md) for allowed values and formats. | | 401 | DECLINED | Indicates that authentication has failed. | Your OAuth signing is incorrect. Re-download your `.p12` file, verify the keystore password and key alias, and confirm you are using the correct consumer key. See [Using OAuth 1.0a](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/). | | 403 | USER_NOT_FOUND | Unable to identify the user | Please contact Mastercard representative to verify access. | | 500 | INTERNAL_SERVER_ERROR | An unexpected error occurred in the application. Reach out to the Mastercard support with any questions. | Retry the request in a few minutes or reach out for help from our [support page](https://developer.mastercard.com/small-business-credit-analytics/documentation/support/index.md#get-help). | ## Next Steps {#next-steps} * [Testing](https://developer.mastercard.com/small-business-credit-analytics/documentation/testing/index.md) --- reproduce and validate these errors in Sandbox * [API Reference](https://developer.mastercard.com/small-business-credit-analytics/documentation/api-reference/index.md) --- endpoint parameters and schemas * [Support](https://developer.mastercard.com/small-business-credit-analytics/documentation/support/index.md#get-help) --- contact support for unresolved issues