Tratamento de Erros

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

Formato Padrão de Erro

number

Código HTTP do erro

number

Código de erro específico da API Martan

string

Mensagem de erro em inglês

object

Mensagens de erro traduzidas

Show Ver estrutura

string

Mensagem em inglês

string

Mensagem em português

object | null

Informações adicionais sobre o erro (quando disponível)

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

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