Erros comuns da API (para o time técnico)

Este artigo é para quem escreve a integração. A referência completa, com exemplos de chamada, fica na página de documentação da API, em /documentacao/api.

401 — chave ausente, inválida ou revogada

A chave vai no cabeçalho Authorization, no formato "Bearer" seguido da chave. Duas causas quase sempre explicam o 401: o cabeçalho não foi enviado no formato esperado, ou a chave foi revogada no painel e uma nova precisa ser gerada.

Não existe recuperar chave: quando ela é gerada, o valor aparece uma vez só. Perdeu, gere outra.

429 — chamadas demais no mesmo minuto

Existe um limite de chamadas por minuto por chave. Ao receber 429, espere e tente de novo — não fique repetindo em laço, porque isso só empurra o limite para frente. Prefira lotes maiores a muitas chamadas pequenas.

422 — o formato do envio está errado

Aqui o lote INTEIRO é recusado e nada é gravado. É erro de estrutura: campo obrigatório ausente, tipo errado, corpo que não é a lista esperada. A resposta aponta o campo. Corrija e reenvie o lote inteiro.

200 — e mesmo assim é preciso ler a resposta

Este é o erro mais comum de quem integra pela primeira vez: tratar 200 como "deu tudo certo" e não olhar o corpo da resposta.

A resposta de sucesso traz DUAS listas: os aceitos e os REJEITADOS, cada rejeitado com o motivo em português. Preço em formato errado e estoque negativo caem aí — geram 200 com o item rejeitado, nunca 422. Se a sua integração ignorar a lista de rejeitados, produtos vão sumir silenciosamente e ninguém vai saber por quê.

Preço e estoque: o formato que passa

Preço é número decimal simples, como 12.90. Não mande símbolo de moeda, não mande separador de milhar, não mande texto. Estoque é número inteiro, zero ou maior.

Mandar o mesmo produto de novo é seguro

O produto é identificado pelo código (SKU) dentro da sua empresa. Reenviar o mesmo código atualiza o produto existente; nunca cria um segundo. Isso vale inclusive quando duas chamadas chegam ao mesmo tempo.

Chave de teste x chave de produção

Produto criado com chave de teste vive num espaço separado e NUNCA chega ao catálogo real nem à Meta. Use a de teste à vontade durante o desenvolvimento — mas confirme qual chave está no ambiente de produção antes de dizer que acabou.

⚠️ Aceito não significa publicado no WhatsApp

Vale repetir, porque é a maior fonte de confusão: um produto aceito pela API está no catálogo interno do OpaChat. Para aparecer na loja dentro do WhatsApp ele ainda precisa ser marcado para envio e passar pela conferência da Meta — que hoje exige FOTO, campo que a API ainda não recebe. Veja o artigo "Por que meu produto não apareceu na loja do WhatsApp".