# Code and Formats source: https://developer.mastercard.com/agent-suite-for-merchants/documentation/code-and-formats/index.md 👉 Keep only the authentication tabs that apply to your service and replace the sample response codes, error structures, and troubleshooting notes with the real behavior your consumers will see. If you change the tab set, keep each auth model in its own `sliding-tabs-item` block and update the included template file so it points to the correct shared partial or service-specific content. ## Overview {#overview} Use this page to document the HTTP status codes, reason codes, gateway errors, and sample error payloads for your service. Tip: Choose the tab that matches your authentication model. Keep only the tabs that apply to your service, or tailor both if this starter is being used for multiple API variants. ## 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. | | 204 (NO CONTENT) | Successful update occurred using a PUT request. | | 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 has insufficient permissions to a resource or action. | | 404 (NOT FOUND) | The requested resource was not found. | | 422 (UNPROCESSABLE ENTITY) | Resource already exists / Resource has been modified. | ## Gateway Error Codes {#gateway-error-codes} Apart from the error codes returned by your API, error codes can also be returned by the Mastercard gateway, which verifies your request signature and routes traffic to the correct destination. For further information about the 4xx 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 Mastercard APIs, the following structure can be used for each error scenario that your API returns. **Single Error:** ```json { "Errors": { "Error": [ { "source": "", "reasonCode": "", "description": "", "recoverable": "e.g. true/false", "details": "One of the request parameters is invalid, try again with the 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 generated and returned by the gateway will have this field set to `Gateway`. If the field value is your service identifier, then the error is generated by your API. | | **ReasonCode** | A unique constant that identifies the error case encountered when your API is called. For example, `FORBIDDEN` can be used when the caller has insufficient permissions for a resource or action. | | **Description** | Description of the `ReasonCode` field provided 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. | 👉 Document your service-specific error codes here. Click [here](https://stage.developer.mastercard.com/jamstack/documentation/content-guide/documentation-guide/#code-and-formats) for guidance on what is expected. ### Sample Errors {#sample-errors} * Sample `400` error response when a `GET` operation contains invalid request parameters: ```json { "Errors": { "Error": [ { "Source": "SAMPLE_API", "ReasonCode": "Bad Request", "Description": "Invalid request content.", "Recoverable": false, "Details": "The identifier supplied in the path is invalid." } ] } } ``` ### API Specific Errors {#api-specific-errors} * Sample API-specific error response when a request field fails validation ```json { "Errors": { "Error": [ { "Source": "countryCode", "ReasonCode": "INVALID_INPUT_VALUE", "Description": "countryCode must be 3 characters in length", "Recoverable": true, "Details": "GBRA is invalid" } ] } } ``` ## Resource API HTTP Status Codes {#resource-api-http-status-codes} 👉 Replace or trim this table so it reflects only the resource-level HTTP responses your OAuth 2.0 protected API actually returns. If your service does not use one of these codes, remove it and document the codes that do apply. The table below covers the most common HTTP status codes returned by your protected resource API endpoints. These are normal business or resource responses, not the full set of OAuth 2.0 token, client assertion, or DPoP validation errors. | 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. | | 204 (NO CONTENT) | Successful update occurred using a PUT request. | | 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 access token. | | 403 (FORBIDDEN) | The user has insufficient permissions to a resource or action. | | 404 (NOT FOUND) | The requested resource was not found. | | 422 (UNPROCESSABLE ENTITY) | Resource already exists / Resource has been modified. | Note: For OAuth 2.0 specifically, authentication and authorization failures from the token endpoint or resource server usually surface as `400`, `401`, or `403` responses with OAuth-style fields such as `error` and `error_description`, rather than the business error structures some resource APIs use. ## Gateway Error Codes {#gateway-error-codes} 👉 Keep this section only if requests to your service can fail at the Mastercard gateway layer. If gateway-level errors are not relevant for your service, remove this section. If they are relevant, add any service-specific troubleshooting notes that callers should know. Apart from the error codes returned by your API, error codes can also be returned by the Mastercard gateway, which verifies your request signature and routes traffic to the correct destination. For further information about the 4xx 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/). ## OAuth 2.0 Error Format {#oauth-20-error-format} 👉 Use this section to explain how OAuth 2.0 authentication and authorization failures are returned for your service. Add any notes about token endpoint behavior, DPoP requirements, or resource-server error handling that are specific to your implementation. Errors from the Mastercard authorization server (token endpoint) and resource server (Mastercard APIs) follow OAuth 2.0 standards from [RFC 6749](https://tools.ietf.org/html/rfc6749#section-5.2) and [RFC 9449](https://tools.ietf.org/html/rfc9449) for DPoP. Typical OAuth 2.0 authentication and authorization error responses use `400`, `401`, or `403`, depending on whether the issue is request formatting, token validity, DPoP proof validation, or insufficient access. OAuth 2.0 errors are returned in JSON with the following format: ```json { "error": "error_code", "error_description": "Human-readable error description" } ``` | Field | Description | |-----------------------|---------------------------------------------------------------| | **error** | Standard OAuth 2.0 error code that identifies the error type. | | **error_description** | Extra details about the error to help you troubleshoot. | ## OAuth 2.0 Error Codes {#oauth-20-error-codes} 👉 Link to the authoritative OAuth 2.0 error-code reference for your service and summarize only the most important auth-layer failures here if your audience needs a shorter guide. If the external Mastercard page is sufficient on its own, say that explicitly. For detailed OAuth 2.0 error codes from the Mastercard authorization server and resource server (including client assertion, DPoP proof, scope, and access token errors), see [OAuth 2.0 Error Codes](https://developer.mastercard.com/platform/documentation/errors-and-troubleshooting/oauth2-error-codes/). ## ISO Country and Currency Codes {#iso-country-and-currency-codes} Note: This section is optional. 👉 If your service does not follow the Mastercard API standards for ISO country and currency codes, document the exact format you use here and call out every field that deviates from the standard. New services should use the standard ISO representations rather than custom code sets. ## Date and Time Formats {#date-and-time-formats} Note: This section is optional. 👉 If your service does not follow the Mastercard API standards for date and time formats, document the exact format here. Be explicit about whether date-only values use `YYYY-MM-DD`, whether timestamps use ISO 8601, whether values are always UTC, and whether offsets or a trailing `Z` are required. Alert: New services will not be onboarded if they do not follow the standards.