# Codes and Formats source: https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/code-and-formats/index.md ## Ethoca Alerts for Merchants Error Codes and Response Formats {#ethoca-alerts-for-merchants-error-codes-and-response-formats} This page documents the error codes, HTTP statuses, and response formats used by the Ethoca Alerts for Merchants APIs. Use this reference when you receive an error response or when designing error handling in your integration. ## Error response structure {#error-response-structure} All service-level errors are returned in a consistent envelope format. The envelope contains an `Errors` object with an `Error` array. Each error item includes the source, reason code, description, recoverability flag, and optional details. ### Example error response {#example-error-response} ```json { "Errors": { "Error": [ { "Source": "alerts-delivery", "ReasonCode": "VALIDATION_FAILURE", "Description": "Invalid date format: 2026-101-209", "Recoverable": true, "Details": "Invalid date format: 2026-101-209" } ] } } ``` ### Error envelope schema {#error-envelope-schema} | Field | Type | Description | |---------------|---------|---------------------------------------------------------------------------------------------------------------------------------| | `Source` | string | Identifies where the error originated: service module (for example, `alerts-delivery`), `Http Client`, or `Gateway` | | `ReasonCode` | string | Unique code identifying the error case; used for routing resolution steps | | `Description` | string | Human-readable short description of what went wrong | | `Recoverable` | boolean | Indicates whether retrying the same request could succeed (for example, `true` for transient errors, `false` for auth failures) | | `Details` | string | Optional detailed explanation with context-specific information | *** ** * ** *** ## HTTP status to reason code mapping {#http-status-to-reason-code-mapping} The following table shows which HTTP status codes the API returns and the corresponding reason codes you may encounter. | HTTP Status | Reason Code | Description | Typical Cause | Resolution | |-------------|------------------------------|--------------------------------------------------------|--------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 200 | (Success) | Request succeeded | Alert retrieved, acknowledged, or outcome submitted successfully | No action needed | | 400 | `VALIDATION_FAILURE` | Request failed client-side validation | Missing required fields, invalid date format, invalid enum value | Check the error details for the specific field; refer to the OpenAPI spec for field constraints | | 400 | `REQUEST_VALIDATION_FAILURE` | Outcome validation failed at the service level | Missing mandatory outcome field like `outcome` or `refundStatus` | Ensure all required outcome fields are present and non-null | | 400 | (Bad Request, unnamed) | Malformed request syntax | Duplicate acknowledgements in a single request, invalid query parameters | Review request payload structure and query parameters against the spec | | 401 | `DECLINED` | OAuth authentication failed or credentials are invalid | Invalid consumer key, missing OAuth header, invalid signature | Verify OAuth 1.0a signature generation; confirm consumer key and `.p12` keystore are correct for the environment | | 403 | (Forbidden) | Request is forbidden or lacks required permissions | Client does not have permission to access the resource | Confirm that your project has been approved for the requested endpoint; contact Ethoca Customer Delivery if access is restricted | | (Gateway) | `DECLINED` | Gateway-level authorization failure | Missing or invalid authentication | Ensure OAuth credentials are present and valid; see [Mastercard Gateway Error Codes](https://developer.mastercard.com/platform/documentation/security-and-authentication/gateway-error-codes/) | *** ** * ** *** ## Service-level error codes {#service-level-error-codes} Service-level errors originate from the Alerts platform and include validation failures, business logic violations, and data-related issues. ### Validation errors {#validation-errors} Validation errors occur when request fields fail schema or business rule checks. | Source | Reason Code | Description | Typical Cause | Resolution | |-------------------|------------------------------|---------------------------------------------|------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------| | `alerts-delivery` | `VALIDATION_FAILURE` | Date format is invalid | Query parameter `from_date` or `to_date` does not match `YYYY-MM-DD` pattern | Use the format `YYYY-MM-DD` for date parameters; verify dates are not in the future | | `alerts-delivery` | `VALIDATION_FAILURE` | Duplicate alert ID in acknowledgement batch | Same `alertId` appears more than once in the same request | Deduplicate alert IDs before sending acknowledgement requests | | `alerts-outcome` | `REQUEST_VALIDATION_FAILURE` | Mandatory field is missing or null | `outcome`, `refundStatus`, `refund.amount`, or `amountStopped` is `null` or absent | Ensure all required fields are populated with valid values per the OpenAPI spec | | `alerts-outcome` | `REQUEST_VALIDATION_FAILURE` | Invalid enum value | `outcome` or `refundStatus` is not a recognized value | Use only documented outcome values: `STOPPED`, `PARTIALLY_STOPPED`, `RESOLVED`, `NOT_FOUND`, etc. | ### Authentication and authorization errors {#authentication-and-authorization-errors} Authentication and authorization errors come from the OAuth layer or gateway and indicate credential or access issues. | Source | Reason Code | Description | Typical Cause | Resolution | |-----------|-------------|------------------------------------------|----------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `Gateway` | `DECLINED` | Unauthorized - Access Not Granted | Invalid OAuth 1.0a signature, missing consumer key, or expired credentials | Regenerate OAuth signature with correct consumer key and signing key from `.p12` keystore; verify keystore password and key alias | | `Gateway` | `DECLINED` | Missing or invalid authentication header | OAuth `Authorization` header is missing or malformed | Add a valid OAuth 1.0a `Authorization` header to all requests; see [Using OAuth 1.0a to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/) | *** ** * ** *** ## Response status codes {#response-status-codes} | HTTP Status | Meaning | Use Case | |------------------|--------------------------------------------------|----------------------------------------------------------------------| | 200 OK | Request succeeded | Alert retrieved, acknowledged, or outcome submitted successfully | | 400 Bad Request | Request is malformed or fails validation | Invalid query parameters, missing fields, duplicate acknowledgements | | 401 Unauthorized | Authentication failed or credentials are invalid | Invalid OAuth signature, missing keystore, incorrect consumer key | | 403 Forbidden | Client lacks permission for the resource | Project not approved for endpoint access | *** ** * ** *** ## Request/response format notes {#requestresponse-format-notes} ### Date and timestamp format {#date-and-timestamp-format} All dates and timestamps in request and response bodies use ISO 8601 format. Examples: * Date only: `2026-01-15` (used in Pull API query parameters) * DateTime with timezone: `2021-06-18T22:11:05+05:00` * DateTime UTC: `2026-01-12T06:15:13.171792Z` For query parameters on `GET /alerts`, use the `YYYY-MM-DD` format for `from_date` and `to_date`. ### Amount format {#amount-format} Monetary amounts are represented as objects with a numeric `value` and a `currencyCode`. The value is a decimal number with currency-specific precision (for example, USD uses 2 decimal places). Example: ```json { "value": 234.56, "currencyCode": "USD" } ``` ### Outcome codes {#outcome-codes} The following table lists valid outcome values for the Outcome API. #### Confirmed Fraud Outcomes {#confirmed-fraud-outcomes} | Outcome Code | Description | |------------------------|---------------------------------------------------------| | `STOPPED` | The order was stopped before fulfillment | | `PARTIALLY_STOPPED` | Part of the order was stopped | | `PREVIOUSLY_CANCELLED` | The transaction was already canceled | | `MISSED` | Too late; the order has shipped or service was consumed | | `NOT_FOUND` | The order could not be found in the system | | `ACCOUNT_SUSPENDED` | The account has been suspended | | `OTHER` | Any other action not covered above | #### Customer Dispute Outcomes {#customer-dispute-outcomes} | Outcome Code | Description | |--------------------------------|--------------------------------------------| | `RESOLVED` | Case resolved with the customer | | `RESOLVED_PREVIOUSLY_REFUNDED` | Refund already processed | | `UNRESOLVED_DISPUTE` | Merchant disagrees with the dispute reason | | `NOT_FOUND` | Alert could not be found in the system | | `OTHER` | Any other outcome as described in comments | ### Refund status codes {#refund-status-codes} The following table lists valid refund status values for the Outcome API. | Refund Status | Description | |----------------|--------------------------------------| | `REFUNDED` | Transaction was refunded | | `NOT_REFUNDED` | Transaction was not refunded | | `NOT_SETTLED` | Transaction did not go to settlement | ### Refund type codes {#refund-type-codes} When you refund a transaction, specify the refund method using one of these codes. | Refund Type | Description | |-------------|---------------------------| | `REFUND` | Cash refund | | `VOUCHER` | Store voucher or credit | | `POINTS` | Loyalty or reward points | | `GIFT_CARD` | Gift card or store credit | *** ** * ** *** ## Gateway error codes {#gateway-error-codes} For authentication and transport-layer errors that originate from the Mastercard Gateway, refer to the comprehensive error code reference: **[Mastercard Gateway Error Codes](https://developer.mastercard.com/platform/documentation/security-and-authentication/gateway-error-codes/)** Common gateway codes include: | Code | Meaning | |------------------------|----------------------------------------------------------------------| | `DECLINED` | Request was declined; typically authentication or permission failure | | `INVALID_REQUEST_BODY` | Request body is malformed or invalid JSON | | `NOT_FOUND` | Resource not found | | `UNAUTHORIZED` | Authentication is required or failed | | `FORBIDDEN` | Access denied | *** ** * ** *** ## Tips for error handling {#tips-for-error-handling} 1. **Check the `Recoverable` flag** : If `true`, your application can safely retry the request. If `false`, retry won't help. Address the underlying cause instead. 2. **Log the `Details` field**: The detailed error information often includes context-specific hints. Log this for debugging. 3. **Distinguish gateway errors from service errors** : Gateway errors have `Source: "Gateway"` and indicate authentication or transport issues. Service errors have sources like `alerts-delivery` and `alerts-outcome`, indicating business logic or validation failures. 4. **Use reason codes for routing**: In your error handling logic, route different reason codes to appropriate handlers. For example: * `VALIDATION_FAILURE` → Check request format * `DECLINED` → Check OAuth credentials * `VALIDATION_FAILURE` (duplicate acknowledge) → Implement deduplication 5. **Test negative scenarios in Sandbox** : Before going to Production, test your error handling paths with the test cases documented in [Testing](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/testing/index.md). *** ** * ** *** ## Next steps {#next-steps} * See [Testing](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/testing/index.md) for concrete negative test cases and examples of these errors in action. * Review the [API Basics](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/api-basics/index.md) page for authentication setup and configuration. * Consult the [API Reference](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/api-reference/index.md) for endpoint-specific status code details.