> ## Documentation Index
> Fetch the complete documentation index at: https://docs.martan.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Tratamento de Erros

> Formato padrão de erros e códigos de erro da API

Todas as respostas de erro seguem um formato padrão consistente, facilitando o tratamento e debugging.

## Formato Padrão de Erro

<ResponseField name="status" type="number">
  Código HTTP do erro
</ResponseField>

<ResponseField name="error_code" type="number">
  Código de erro específico da API Martan
</ResponseField>

<ResponseField name="message" type="string">
  Mensagem de erro em inglês
</ResponseField>

<ResponseField name="user_message" type="object">
  Mensagens de erro traduzidas

  <Expandable title="Ver estrutura">
    <ResponseField name="en_us" type="string">
      Mensagem em inglês
    </ResponseField>

    <ResponseField name="pt_br" type="string">
      Mensagem em português
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="more_info" type="object | null">
  Informações adicionais sobre o erro (quando disponível)
</ResponseField>

## Códigos de Erro por Categoria

### Autenticação

| Status | Código  | Descrição                                      |
| ------ | ------- | ---------------------------------------------- |
| 401    | 8121200 | API key ausente no header X-API-Key            |
| 417    | 8121201 | Store ID ausente no header X-Store-Id          |
| 401    | 8121202 | API key inválida ou inativa                    |
| 401    | 8121203 | Store inativa                                  |
| 401    | 8121204 | API key expirada                               |
| 403    | 8121205 | Store ID não corresponde à API key             |
| 403    | 8121206 | Limite de uso de pedidos excedido para o plano |

### Orders

| Status | Código | Descrição                                   |
| ------ | ------ | ------------------------------------------- |
| 400    | 802030 | Body JSON mal formatado ou validação falhou |
| 422    | 103    | Pedido já existe (duplicado)                |

### Products

| Status | Código | Descrição                                           |
| ------ | ------ | --------------------------------------------------- |
| 400    | 802030 | Body JSON mal formatado ou validação falhou         |
| 422    | 103    | Produto já existe (mesmo `product_id` e `store_id`) |
| 500    | 520    | Erro inesperado ao buscar ou criar produto          |

## Exemplos de Respostas de Erro

### Erro de Validação

<ResponseExample>
  ```json theme={null}
  {
    "status": 400,
    "error_code": 802030,
    "message": "Bad-formatted JSON body, details in user_message",
    "user_message": {
      "en_us": "products: Array must contain at least 1 element(s)",
      "pt_br": "products: Array must contain at least 1 element(s)"
    },
    "more_info": null
  }
  ```
</ResponseExample>

**Causas comuns:**

* Array vazio em `products` ou `customers`
* Campo obrigatório ausente
* Tipo de dado incorreto
* Valor fora do intervalo permitido (ex: preço negativo)

### Erro de Duplicação (Orders)

<ResponseExample>
  ```json theme={null}
  {
    "status": 422,
    "error_code": 103,
    "message": "Order has already been sent",
    "user_message": {
      "en_us": "Duplicated, Order has already been sent",
      "pt_br": "Pedido já encontra-se criado"
    },
    "more_info": null
  }
  ```
</ResponseExample>

**Causa:** Já existe um pedido com o mesmo `order_id` e `store_id`.

**Solução:** Use um `order_id` único ou verifique se o pedido já foi criado anteriormente.

### Erro de Duplicação (Products)

<ResponseExample>
  ```json theme={null}
  {
    "status": 422,
    "error_code": 103,
    "message": "Product has already been sent",
    "user_message": {
      "en_us": "Duplicated, Product has already been sent",
      "pt_br": "Produto já encontra-se criado"
    },
    "more_info": null
  }
  ```
</ResponseExample>

**Causa:** Já existe um produto com o mesmo `product_id` e `store_id`.

**Solução:** Use um `product_id` único ou atualize o produto existente.

### Erro de Limite de Uso

<ResponseExample>
  ```json theme={null}
  {
    "status": 403,
    "error_code": 8121206,
    "message": "Order usage limit exceeded",
    "user_message": {
      "en_us": "Order usage limit exceeded for your plan",
      "pt_br": "Limite de uso de pedidos excedido para o seu plano"
    },
    "more_info": null
  }
  ```
</ResponseExample>

**Causa:** O plano da sua conta atingiu o limite de pedidos permitidos.

**Solução:** Entre em contato com o suporte ou faça upgrade do seu plano.

### Erro de Autenticação

<ResponseExample>
  ```json theme={null}
  {
    "status": 401,
    "error_code": 8121202,
    "message": "Invalid or inactive API key",
    "user_message": {
      "en_us": "Invalid or inactive API key",
      "pt_br": "API key inválida ou inativa"
    },
    "more_info": null
  }
  ```
</ResponseExample>

**Causas comuns:**

* API key ausente no header
* API key inválida ou inativa
* API key expirada
* API key não é do tipo `orders`

**Solução:** Verifique se a API key está correta e ativa no painel da Martan.

### Erro de Store ID

<ResponseExample>
  ```json theme={null}
  {
    "status": 403,
    "error_code": 8121205,
    "message": "Store ID does not match API key",
    "user_message": {
      "en_us": "Store ID does not match API key",
      "pt_br": "Store ID não corresponde à API key"
    },
    "more_info": null
  }
  ```
</ResponseExample>

**Causa:** O `X-Store-Id` fornecido não corresponde à store associada à API key.

**Solução:** Verifique se o `X-Store-Id` está correto e corresponde à store da sua API key.

## Tratamento de Erros no Código

### JavaScript/TypeScript

```typescript theme={null}
try {
  const response = await fetch('https://api.appmartan.com.br/orders', {
    method: 'POST',
    headers: {
      'X-API-Key': 'sua-api-key',
      'X-Store-Id': '123',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(orderData)
  });

  if (!response.ok) {
    const error = await response.json();

    switch (error.error_code) {
      case 802030:
        console.error('Erro de validação:', error.user_message.pt_br);
        break;
      case 103:
        console.error('Duplicação:', error.user_message.pt_br);
        break;
      case 8121206:
        console.error('Limite excedido:', error.user_message.pt_br);
        break;
      default:
        console.error('Erro desconhecido:', error);
    }

    throw new Error(error.user_message.pt_br);
  }

  const result = await response.json();
  console.log('Pedido criado:', result.id);
} catch (error) {
  console.error('Erro na requisição:', error);
}
```

## Boas Práticas

1. **Sempre verifique o status HTTP**: Use `response.ok` ou verifique o código de status antes de processar a resposta.

2. **Trate erros específicos**: Use os códigos de erro para implementar lógica específica para cada tipo de erro.

3. **Exiba mensagens ao usuário**: Use `user_message.pt_br` ou `user_message.en_us` para exibir mensagens amigáveis.

4. **Log de erros**: Registre os erros completos para debugging, incluindo `error_code` e `message`.

5. **Retry para erros temporários**: Implemente retry logic para erros 5xx (erros do servidor).