# Обработка ошибок

## Общая схема ответа с ошибкой

<Tabs defaultValue="json" className="w-full">
    <TabsList className="flex w-max gap-2">
      <TabsTrigger value="json">JSON</TabsTrigger>
      <TabsTrigger value="xml">XML</TabsTrigger>
    </TabsList>
  <TabsContent value="json">
    ```json
    {
      "status":"{Статус ошибки}",
      "errorMessage":"{Текст ошибки}",
      "errorId":"{Идентификатор ошибки}",
      "httpStatusCode":"{HTTP-код ошибки}"
    }
    ```
  </TabsContent>
  <TabsContent value="xml">
  ```xml
  <result>
    <status>{Статус ошибки}</status>
    <errorMessage>{Текст ошибки}</errorMessage>
    <errorId>{Идентификатор ошибки}</errorId>
    <httpStatusCode>{HTTP-код ошибки}</httpStatusCode>
  </result>
  ```
   </TabsContent>
</Tabs>

| Имя | Описание |
| :-------------- | :-------------------------- |
| status | Статус ошибки. Описание статусов и причины ошибок в разделе ниже |
| errorMessage | Описание ошибки |
| errorId | Идентификатор ошибки в формате UUID. Может отсутствовать |
| httpStatusCode | HTTP-код ошибки |

## Коды и статусы ошибок

| Код ответа HTTP | Status в теле ответа        | Причина                                     | Можно повторять запрос |
| :-------------- | :-------------------------- | :------------------------------------------ | :--------------------- |
| 200             | TransactionAlreadyProcessed | Операция уже была успешно обработана        | Нет                    |
| 200             | ValidationError             | Ошибка в данных введенных, клиентом         | Нет                    |
| 400             | ProtocolError               | Ошибка в запросе                            | Нет                    |
| 401             | ProtocolError               | Отсутствуют данные для авторизации          | Нет                    |
| 403             | ProtocolError               | Неправильные данные авторизации             | Нет                    |
| 404             | Отсутствует                 | Неправильный url запроса                    | Нет                    |
| 429             | ProtocolError               | Превышен лимит вызова одной операции в день | Нет                    |
| 500             | InternalServerError         | Временная недоступность Mindbox             | Да                     |
| 502             | Отсутствует                 | Временная недоступность Mindbox             | Да                     |
| 503             | InternalServerError         | Временная недоступность Mindbox             | Да                     |
| 504             | Отсутствует                 | Временная недоступность Mindbox             | Да                     |

### Операция уже была успешно обработана

<Tabs defaultValue="json" className="w-full">
    <TabsList className="flex w-max gap-2">
      <TabsTrigger value="json">JSON</TabsTrigger>
      <TabsTrigger value="xml">XML</TabsTrigger>
    </TabsList>
  <TabsContent value="json">
```json
{
  "status":"TransactionAlreadyProcessed"
}
```
  </TabsContent>
  <TabsContent value="xml">
```xml
<result>
    <status>TransactionAlreadyProcessed</status>
</result>
```
   </TabsContent>
</Tabs>

Означает, что транзакция с переданным уникальным идентификатором уже была обработана. 

Если вы реализовали очередь запросов и повторяете запрос до тех пор пока он не обработается, то это нормальная ситуация. Если вы не повторяете запросы, то такой ответ означает, что вы передали неуникальный идентификатор транзакции.

### Ошибка в данных, введенных клиентом

<Tabs defaultValue="json" className="w-full">
    <TabsList className="flex w-max gap-2">
      <TabsTrigger value="json">JSON</TabsTrigger>
      <TabsTrigger value="xml">XML</TabsTrigger>
    </TabsList>
  <TabsContent value="json">
```json
{
  "status":"ValidationError",
  "validationMessages": [
    {
      "message":"\"mymail\" не является корректным адресом электронной почты.",
      "location":"/customer/email"
    },
    {
      "message":"Заполните хотя бы один контакт."
    }
  ]
}
```
   </TabsContent>
  <TabsContent value="xml">
```xml
<result>
    <status>ValidationError</status>
    <validationMessages>
        <validationMessage>
            <message>mymail не является корректным адресом электронной почты.</message>
            <location>/operation/customer/email</location>
        </validationMessage>
        <validationMessage>
            <message>Заполните хотя бы один контакт.</message>
        </validationMessage>
    </validationMessages>
</result>
```
   </TabsContent>
</Tabs>

Возвращается в случае ошибок в данных, введенных клиентом.

Если вы полагаетесь на валидацию данных на стороне Mindbox, необходимо отобразить клиенту сообщение с ошибкой:

* Если заполнен тег location, сообщение об ошибке можно показать рядом с соответствующим ему полем. В location пишется xpath поля, с которым связана ошибка.
* Если тег location отсутствует, сообщение об ошибке относится к запросу в целом и его стоит отображать где-то в общей части.

Автоматически повторять тот же запрос в случае таких ошибок нельзя. Нужно отправить новый запрос после того, как клиент поправит ошибки в введенных данных.

### Неправильный вызов операции

<Tabs defaultValue="json" className="w-full">
    <TabsList className="flex w-max gap-2">
      <TabsTrigger value="json">JSON</TabsTrigger>
      <TabsTrigger value="xml">XML</TabsTrigger>
    </TabsList>
  <TabsContent value="json">
```json
{
  "status":"ProtocolError",
  "errorMessage":"{текст ошибки}",
  "errorId":"{UUID ошибки}",
  "httpStatusCode":"{http-код ошибки}"
}
```
   </TabsContent>
  <TabsContent value="xml">
```xml
<result>
    <status>ProtocolError</status>
    <errorMessage>{текст ошибки}</errorMessage>
    <errorId>{UUID ошибки}</errorId>
    <httpStatusCode>{http-код ошибки}</httpStatusCode>
</result>
```
   </TabsContent>
</Tabs>

httpStatusCode дублирует код ответа HTTP.

В случае возникновениях таких ошибок, надо исправлять интеграцию. Уточните у менеджера, что именно надо поправить.

Автоматически повторять тот же запрос в случае таких ошибок нельзя. Если важно не потерять данные, стоит сохранить данные запроса, чтобы можно было его поправить и выполнить исправленную версию.

### Временная недоступность Mindbox

<Tabs defaultValue="json" className="w-full">
    <TabsList className="flex w-max gap-2">
      <TabsTrigger value="json">JSON</TabsTrigger>
      <TabsTrigger value="xml">XML</TabsTrigger>
    </TabsList>
  <TabsContent value="json">
```json
{
  "status":"InternalServerError",
  "errorMessage":"{текст ошибки}",
  "errorId":"{UUID ошибки}",
  "httpStatusCode":"{http-код ошибки}"
}
```
   </TabsContent>
  <TabsContent value="xml">
```xml
<result>
    <status>InternalServerError</status>
    <errorMessage>{текст ошибки}</errorMessage>
    <errorId>{UUID ошибки}</errorId>
    <httpStatusCode>{http-код ошибки}</httpStatusCode>
</result>
```
   </TabsContent>
</Tabs>

Ошибка связана с временными проблемами на стороне mindbox или проблемами на уровне сети. Подробности можно уточнить у менеджера.

В случае подобной ошибки можно повторить запрос:

* Если он не меняет данные (например, запрос получения данных клиента)
* Если в запросе передается уникальный идентификатор транзакции (при повторе надо передавать тот же идентификатор, что и при первом запросе)