# Code and Formats source: https://developer.mastercard.com/mastercard-agent-pay/documentation/code-and-formats/index.md 👉 Document your service HTTP error codes and Gateway error codes here. Click [here](https://stage.developer.mastercard.com/jamstack/documentation/content-guide/documentation-guide/#code-and-formats) for documentation about what is expected. ## 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 the {Pet Store} 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 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 all Mastercard APIs, the following structure is followed by the {Pet Store} API for each error scenario that can occur. **Single Error:** ```json { "Errors": { "Error": [ { "source": "", "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 that is generated and returned by the Gateway will have this field set to `Gateway`. If the field value is `PETSTORE_API`, then the error is generated by the {Pet Store} application. | | **ReasonCode** | A unique constant identifies the error case encountered when any {Pet Store} API is called. For example, `FORBIDDEN` is used when the user has insufficient permissions to 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 sample service specific error codes here. Click [here](https://stage.developer.mastercard.com/jamstack/documentation/content-guide/documentation-guide/#code-and-formats) for documentation about what is expected. ### Sample Errors {#sample-errors} * Sample `400` error response when the `GET /cats or GET /dogs` operation contains invalid request parameters: ```json { "Errors": { "Error": [ { "Source": "PETSTORE_API", "ReasonCode": "Bad Request", "Description": "Invalid request content.", "Recoverable": false, "Details": "The UUID which identifies the pet is invalid." } ] } } ``` ### API Specific Errors {#api-specific-errors} * Sample API specific error response when the `country code` is less than the specified minLength ```json { "Errors": { "Error": [ { "Source": "countryCode", "ReasonCode": "INVALID_INPUT_VALUE", "Description": "countryCode must be 3 characters in length", "Recoverable": true, "Details": "GBRa' is invalid" } ] } } ``` ### Date Time Formatting {#date-time-formatting} 👉 Mention the date time formatting if your service uses dates or times. Note: Note that this mandated by the OpenAPI standards for this type
* Date and time formats that are described as type string in your OpenAPI 3 specification must follow the ISO8601 standard () * Date and time formats that are described as type date-time in your OpenAPI 3 specification must follow the RFC 3339 standard () Note: Note that the "T" appears literally in the string, to indicate the beginning of the time element, as specified in ISO 8601. If you are using RFC 3339, then you can replace the T with a space. * The formats are as follows. Exactly the components shown here must be present, with exactly this punctuation: Year: ```yaml YYYY (eg 1997) ``` Year and month: ```yaml YYYY-MM (eg 1997-07) ``` Complete date: ```yaml YYYY-MM-DD (eg 1997-07-16) ``` Complete date plus hours and minutes: ```yaml YYYY-MM-DDThh:mmTZD (eg 1997-07-16T19:20+01:00) ``` Complete date plus hours, minutes and seconds: ```yaml YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) ``` Complete date plus hours, minutes, seconds and a decimal fraction of a second: ```yaml YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.45+01:00) ``` Where: ```yaml YYYY = four-digit year MM = two-digit month (01=January, etc.) DD = two-digit day of month (01 through 31) hh = two digits of hour (00 through 23) (am/pm NOT allowed) mm = two digits of minute (00 through 59) ss = two digits of second (00 through 59) s = one or more digits representing a decimal fraction of a second TZD = time zone designator (Z or +hh:mm or -hh:mm) ``` #### Differences between the two standards: {#differences-between-the-two-standards} This is acceptable in ISO 8601 and RFC 3339 (with T): ```yaml 2019-10-12T07:20:50.52Z ``` This is only accepted in RFC 3339 (without T): ```yaml 2019-10-12 07:20:50.52Z ``` ### ISO 20022 Formatting {#iso-20022-formatting} 👉 Mention ISO20022 formatting only if it is used by your service. ISO20022 ISO 20022 is a multipart International Standard prepared by ISO Technical Committee TC68 Financial Services. It describes a common platform for the development of messages using: 1. A modelling methodology to capture in a syntax-independent way financial business areas, business transactions and associated message flows; 2. A central dictionary of business items used in financial communications; 3. A set of XML and ASN design rules to convert the message models into XML or ASN schemas, whenever the use of the ISO 20022 XML or ASN-based syntax is preferred. * It is important that product owners and developers are aware of this broad ranging standard for language across five financial business domains. It will help with consistency across a range of language so our customers have a better understanding as they use more and more of our APIs. * ISO20022 website -