# Code and Formats source: https://developer.mastercard.com/issuer-enrollment/documentation/code-and-formats/index.md ## API Gateway Errors {#api-gateway-errors} The API Gateway can reject a request before it reaches an API, for example, when request signing or routing fails. Gateway errors are distinct from application errors returned by an API. For further information about the current Gateway response format, response codes, and their possible resolutions, see [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/errors-and-troubleshooting/oauth1-and-mtls-error-codes/). ## Server API Errors {#server-api-errors} When an API rejects a server-side request, the response includes an HTTP status and an API error object. The exact status codes, reason codes, and error details depend on the operation; use that operation's API reference as the source of truth. Note: Refer to the [error codes returned for the MDES Token Connect API](https://developer.mastercard.com/mdes-token-connect/documentation/code-and-formats/). ### Error Format and Example {#error-format-and-example} * JSON ```JSON { "status": "", "reason": "", "message": "", "errordetail": [ { "reason": "", "sourceType": "", "message": "", "source": "" } ] } ``` * JSON ```JSON { "status": 400, "reason": "INVALID_ARGUMENT", "message": "Cannot process the request because it is malformed or has incorrect/missing fields or values.", "errordetail": [ { "reason": "CANNOT_BE_NULL", "sourceType": "BODY", "message": "must not be null", "source": "srcClientId" } ] } ``` ### Attributes {#attributes} | Name | Type | Description | |-----------------------------------------------------------------------------------------------------------------------------|------------------|-----------------------------------------------------------------------------------------------------------------------------| | [**reason**](https://developer.mastercard.com/issuer-enrollment/documentation/code-and-formats/index.md#error-reason-codes) | String | API reason code for the error. | | [**status**](https://developer.mastercard.com/issuer-enrollment/documentation/code-and-formats/index.md#http-status-codes) | Number | HTTP status code. | | [**message**](https://developer.mastercard.com/issuer-enrollment/documentation/code-and-formats/index.md#error-message) | String | Error message to be displayed for integrator. | | [**errordetail**](https://developer.mastercard.com/issuer-enrollment/documentation/code-and-formats/index.md#error-detail) | Array of objects | Optional operation-specific details about the error. Each detail can identify the reason, source type, message, and source. | #### Error Reason Codes {#error-reason-codes} The following table gives general guidance for common API reason codes. A code is not necessarily returned by every operation; see the operation reference for its supported codes and examples. | Reason code | Meaning | Recoverability and action | |-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **INVALID_ARGUMENT** | The request is malformed or contains a missing, invalid, or unsupported value. | Recoverable after correcting the request. Use `source` and `sourceType` from `errordetail` to locate the field; do not retry the unchanged request. | | **INVALID_STATE** | The request is not valid for the resource's current state or fails a business validation. | Recoverable only after resolving the state conflict or changing the request as required by the operation. Retrying the unchanged request is not expected to resolve the error. | | **UNAUTHENTICATED** | The API did not accept the supplied authentication credentials. This API reason is distinct from HTTP status `401 Unauthorized` and Gateway errors. | Check the operation's authentication requirements and correct the credentials, token, or signature. | | **NOT_FOUND** | The requested resource or identifier (such as batchID) was not found. | Recoverable if the identifier or request is corrected, or the required resource is made available. Verify the identifier before trying again. | | **PERMISSION_DENIED** | The client is not permitted to access the resource, or an identity or permission check failed. | Recoverable only after access or client configuration is corrected. Contact your Mastercard representative if access should be allowed; do not repeat the unchanged request. | | **UNAVAILABLE** | The server is temporarily unable to process the request. | Potentially transient. Retry only when the operation's reference confirms retry is appropriate and repeating it is safe. Honor a returned `Retry-After` value; otherwise follow that operation's retry guidance. If a write outcome is uncertain, check its status or idempotency guidance before retrying. | | **INTERNAL** | An internal server error occurred. | Potentially transient, but retry only when the operation's reference confirms the request can safely be repeated. | #### HTTP Status Codes {#http-status-codes} | Status | Detail | |-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 200 - OK | The operation succeeded. Consult its response schema for the returned data. | | 202 - Accepted | The request was accepted for asynchronous processing. For batch enrollment, use the returned batch ID with [Check batch status](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#getDirectoryBatchStatus); see the [batch enrollment API](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#batchCredentialsInDirectory) for its response details. | | 400 - Bad Request | The operation rejected the request. For example, this error may occur if `SRC-Correlation-Id` is missing or incorrect in the API request. Inspect the API error object and correct the request using its `reason`, `message`, and any `errordetail` values. | | 401 - Unauthorized | Authentication failed. The Gateway may return this status, for example, when request signing (OAuth signature) is invalid. Follow the Gateway or operation-specific authentication guidance for the response received. | | 403 - Forbidden | The request was understood but access was denied. Verify the client identity and permissions using the operation-specific guidance; see the response error object when provided. For example, this error may be returned if the `SRC-Client-Id` is missing or incorrect in the request body, or if the combination of `SRC-Correlation-Id` and `SRC-DSA-Id` is incorrect. | | 404 - Not Found | The requested resource or identifier was not found. Check the operation reference for the relevant resource and path parameters. For example, this error may be returned if a checkout transaction is not found. | | 500 - Internal Server Error | An internal error occurred. Inspect the API error response and follow the operation's retry guidance. | | 503 - Service Unavailable | The service is temporarily unavailable. Follow the operation's retry guidance and any `Retry-After` value returned. | These descriptions are general. Not every operation returns every status, and the response schema may vary. The operation-level response definitions in the [API Reference](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md) specify the supported responses. #### Where to Find Operation-Specific Errors {#where-to-find-operation-specific-errors} Use the response definitions for the operation you called to confirm which status and reason codes it can return. The mappings below are representative workflow contexts based on documented responses, not frequency rankings or a guarantee that every linked operation returns every code. Some OpenAPI specifications define shared error-code enums, so use the operation's response examples and schema as the source of truth. | Representative error code(s) | Example workflow context | Operation references to check | |------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `UNAUTHENTICATED`, `PERMISSION_DENIED` | Authentication or access checks, before or while an API processes a request. Determine whether the response came from the Gateway or the API. | [Sessions and Bind APIs](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#authentication-apis), the operation's security requirements, and [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/gateway-error-codes/). | | `INVALID_ARGUMENT` | Request validation during enrollment submission or profile/credential creation and updates. | [Submit a batch](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#batchCredentialsInDirectory), [create a digital credential](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#createDigitalCredential), [update credential](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#updateCredentialsByExternalCredentialId), and [update profile](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#updateProfileByExternalConsumerId). | | `INVALID_STATE` | Business or resource-state validation during enrollment processing or lifecycle changes. | [Submit a batch](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#batchCredentialsInDirectory), [check batch status](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#getDirectoryBatchStatus), and the relevant [lifecycle operations](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#lifecycle-management-apis). | | `NOT_FOUND` | Batch-status polling with an unknown batch ID, or lookup of a credential or profile that cannot be found. | [Check batch status](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#getDirectoryBatchStatus), [get credential](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#getCredentialByExternalCredentialId), and [get profile](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#getProfileByExternalConsumerId). | | `AMBIGUOUS_CONSUMER_IDENTITY` (`errordetail.reason`) | Consumer identity matching during enrollment; asynchronous batch results can report the issue on an individual record. | [Submit a batch](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#batchCredentialsInDirectory), [check batch status](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#getDirectoryBatchStatus), and [create a digital credential](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#createDigitalCredential). | | `NO_RESPONSE_FROM_ISSUER` (`errordetail.reason`) | Asynchronous enrollment processing when an issuer response is not received; inspect the operation or batch result before retrying. | [Check batch status](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#getDirectoryBatchStatus) and the relevant enrollment operation. | | `INTERNAL`, `UNAVAILABLE` | Service-side failures can occur during any operation; retry and status checks depend on the operation and whether the request is safe to repeat. | The response definition for the operation that returned the error. | | MDES Token Connect | Consult the product-specific error guidance. | See the [MDES Token Connect error documentation](https://developer.mastercard.com/mdes-token-connect/documentation/code-and-formats/) and the relevant MDES operation reference. | #### Error Message {#error-message} The `message` field provides a human-readable summary. Use the operation's documented `reason` and `errordetail` fields to determine the cause and action; message text can vary by operation and response. The following table shows examples of top-level `reason` values and their associated messages. These are distinct from the operation-specific `errordetail[].reason` values shown in the [Error Detail](https://developer.mastercard.com/issuer-enrollment/documentation/code-and-formats/index.md#error-detail) section. The next steps are general guidance; follow the operation reference for supported recovery and retry behavior. For any write with an uncertain outcome, check operation status or idempotency guidance before retrying. | Reason | Message | Resolution tips | |-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | INVALID_ARGUMENT | Cannot process the request because it contains invalid, missing, or incorrectly formatted data. | Review `errordetail`, `source`, and `sourceType` to identify the invalid field. Correct the input according to the operation schema and submit the updated request. Do not retry the same request unchanged. | | INVALID_STATE | The request cannot be completed because one or more field values are not valid for the current resource state. | Review the current resource state and operation-specific business rules. Correct the conflicting values and submit the updated request. Do not retry the same request unchanged. | | UNAUTHENTICATED | Required authentication credentials are missing or invalid. For example, a required JWT token is missing or invalid. This API reason is distinct from HTTP status `401 Unauthorized`. | Verify the authentication credentials, token, signature, and required authentication headers. Correct any issues and retry the request. | | PERMISSION_DENIED | Access to the requested resource is denied. | Verify that the client is onboarded and has the permissions required for the operation. If access should be granted, contact your administrator or Mastercard representative. Do not retry the same request unchanged. | | INTERNAL | An internal server error occurred while processing the request. | Capture the response and correlation identifier. For requests with uncertain outcomes, verify the resource status before retrying. Retry only if the operation supports safe retries. | | UNAVAILABLE | The service is temporarily unavailable. | Follow the operation's retry guidance and honor any `Retry-After` value returned in the response. For requests with uncertain outcomes, verify the resource status before resubmitting. | | NOT_FOUND | The requested resource was not found. | Verify that the resource identifier is correct and that the resource exists. Retry only after correcting the identifier or making the resource available. | | ABORTED | The request could not be completed because of a concurrent update conflict. | Retrieve the latest resource state, update the request as needed, and retry only if the operation supports safe retries. | | ALREADY_EXISTS | The resource already exists. | Verify the resource identifier and use the appropriate read or update operation if applicable. Do not repeat the create request unchanged. | | RESOURCE_EXHAUSTED | Resource limits or rate limits have been exceeded. | Follow the operation's quota and rate-limit guidance. Honor any `Retry-After` value and retry only when permitted by the operation. | | CANCELLED | The request was cancelled before processing completed. | Verify the operation status before resubmitting, especially for write operations. Retry only if the operation confirms that it is safe to do so. | | DATA_LOSS | Unrecoverable data loss or corruption was detected. | Stop retrying the request. Preserve the response and correlation identifier, and contact support using the documented support process. | | LOCKED | Access to the requested resource is restricted because the client has been locked. | Verify the client status, onboarding, and permissions. Contact your administrator or Mastercard representative to resolve the lock before retrying. | | NOT_IMPLEMENTED | The requested operation is not supported. | Review the API documentation and use a supported operation. Retrying the same request will not resolve the issue. | | DEADLINE_EXCEEDED | The request did not complete within the configured time limit. | Verify the operation status before retrying, particularly for write operations. Retry only when supported by the operation and safe to repeat. | | INVALID_CONFIGURATION | The request could not be processed because of an invalid or missing configuration. | Review the client and service configuration required by the operation. Correct any configuration issues before retrying. Contact your administrator or Mastercard representative if assistance is required. | #### Error Detail {#error-detail} The `errordetail` field is an optional list of operation-specific details. Its available reason values are not identical across all APIs; the operation schema is authoritative. The values below are examples used by Issuer Enrollment APIs. Use `source` and `sourceType` to locate the failing input or resource, then check the operation reference before retrying. Do not retry an unchanged request; for transient errors, retry only when the operation permits it and repeating the request is safe. * `reason` - Identifies the specific type of error. The values shown are examples; supported values vary by operation. See the operation schema for the complete enum. | Reason | Description | Recommended action and retry guidance | |--------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | CANNOT_BE_NULL | The supplied value is null or missing when a value is required for the requested operation. | Identify the missing or null field, provide the required value, and submit the corrected request. Do not retry unchanged. | | INVALID_VALUE | The supplied value has the correct data type but is not supported or allowed for the requested operation. | Check the operation schema and allowed values, correct the field, and resubmit. Do not retry unchanged. | | PAN_INELIGIBLE | The supplied PAN is not eligible for the requested operation based on the applicable eligibility requirements. | Verify the card and operation eligibility with the issuer or relevant operation guidance. Retry only if eligibility or request data changes. | | INVALID_FORMAT | The supplied value does not follow the required format for the requested field or operation. | Check the operation schema for the expected format, correct the value, and resubmit. Do not retry unchanged. | | ALREADY_EXISTS | The entity or resource being created or registered already exists in the system. | Verify the resource identifier and use the documented read or update operation if appropriate. Do not repeat a create request unchanged. | | NOT_FOUND | The supplied value, entity, or resource identifier could not be found in the system. | Verify the identifier and whether the resource must already exist for the operation. Retry only after correcting the identifier or making the resource available. | | INVALID_STATE | The field or resource state is incompatible with the operation. | Use the detail message and source to identify the state conflict, then follow the operation's requirements to resolve it. Do not retry unchanged. | | AMBIGUOUS_CONSUMER_IDENTITY | The supplied consumer identities partially matched a profile, but an identity field such as email or phone did not match. | Verify the supplied identity fields against the operation's matching requirements and resolve the mismatch before resubmitting. Do not retry unchanged. | | ISSUER_DECLINED | The issuer declined the request and did not approve the requested operation. | Follow issuer-specific or operation-specific guidance to resolve the decline. Do not repeat the unchanged request. | | TOKENIZATION_INELIGIBLE | Tokenization is not available for the supplied PAN or is not permitted for the requested operation under the applicable eligibility requirements. | Verify tokenization eligibility and operation requirements. Do not retry unchanged unless eligibility or request data changes. | | INVALID_PAN | The supplied PAN is invalid for the requested operation and does not meet the applicable card-data requirements. | Check the supplied card data against the operation requirements and correct it before resubmitting. Do not retry unchanged. | | CORRUPT_DATA | The data associated with the entity is corrupted or cannot be processed reliably for the requested operation. | Avoid repeated write attempts. Capture the request or correlation identifier and contact support through the operation's documented support path. | | EXPIRED | The card associated with the request has expired and may no longer be eligible for the requested operation. | Verify the card and use a current eligible card if the operation supports it. Retry only after correcting the expired data. | | MULTIPLE_FOUND | Multiple accounts or matching entities were found when the operation expected a single unambiguous result. | Supply more specific identifiers or resolve the ambiguity before resubmitting. Do not retry unchanged. | | NO_RESPONSE_FROM_ISSUER | The issuer did not respond to the network message within the allotted time. An asynchronous message may be sent to communicate the outcome. | Honor the operation's Retry-After value and retry guidance. For a write operation, check status or idempotency guidance before resubmitting to avoid duplicating an operation with an uncertain outcome. | | INVALID_TOKEN_UNIQUE_REFERENCE | The Token Unique Reference (TUR) supplied in the request could not be found. | Verify the TUR and confirm that it belongs to the expected token and requestor. Do not retry unchanged. | | TOKEN_MIGRATION_NOT_ELIGIBLE | The token is not in a status that permits migration under the applicable token migration requirements. | Check the token's current status and migration requirements. Use the documented alternative or retry only after eligibility changes. | | INVALID_TOKEN_REQUESTOR_ID | The client is not authorized for the requested TRID, or the TUR belongs to a different TRID than the one specified in the request. | Verify the TRID, client authorization, and TUR association before resubmitting. Do not retry unchanged. | | UNEXPECTED_ERROR | An unexpected error occurred while processing the request, preventing the operation from completing as expected. | Capture the request or correlation identifier and check operation-specific status and retry guidance. Retry only if the operation allows it and the request is safe to repeat. | | SUSPENDED_CARD | The issuer has suspended the card, making it ineligible for use in operations that require an active card. | Resolve the card status with the issuer. Do not retry until the card is eligible and the operation permits it. | | ACCOUNT_RANGE_NOT_FOUND | The consumer account range associated with the supplied card data could not be found. | Verify the card data and supported account range. Contact the issuer or support path if the data is correct. Do not retry unchanged. |
* `sourceType` - Identifies the part of the request where the error occurred. The `sourceType` element is a string enum value and will be one of: | sourceType | Description | |------------|-----------------------------------------------| | BODY | Refers to the body of the request. | | HEADER | Refers to any headers set in the request. | | QUERY | Any parameters set in the query string. | | PATH | Any parameter set in the path of the service. | | METHOD | Refers to the request method. |
* `message` - Custom error message released by the application. * `source` - Specifies the reason/location of the parameter in the request, which generated the error.