Skip to main content

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.

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

​
Formato Padrão de Erro

​
status
number
Código HTTP do erro
​
error_code
number
Código de erro específico da API Martan
​
message
string
Mensagem de erro em inglês
​
user_message
object
Mensagens de erro traduzidas
​
more_info
object | null
Informações adicionais sobre o erro (quando disponível)

​
Códigos de Erro por Categoria

​
Autenticação

StatusCódigoDescrição
4018121200API key ausente no header X-API-Key
4178121201Store ID ausente no header X-Store-Id
4018121202API key inválida ou inativa
4018121203Store inativa
4018121204API key expirada
4038121205Store ID não corresponde à API key
4038121206Limite de uso de pedidos excedido para o plano

​
Orders

StatusCódigoDescrição
400802030Body JSON mal formatado ou validação falhou
422103Pedido já existe (duplicado)

​
Products

StatusCódigoDescrição
400802030Body JSON mal formatado ou validação falhou
422103Produto já existe (mesmo product_id e store_id)
500520Erro inesperado ao buscar ou criar produto

​
Exemplos de Respostas de Erro

​
Erro de Validação

{
  "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
}
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)

{
  "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
}
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)

{
  "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
}
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

{
  "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
}
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

{
  "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
}
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

{
  "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
}
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

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).