Erros e retornos

Formato padrão dos erros, tabela de status codes e como reagir a cada um. Vale para todos os endpoints /api/v1.

Formato

Em caso de sucesso, a resposta é sempre JSON com o respectivo status 2xx. Em caso de erro, o corpo é um JSON com o campo error (mensagem legível). Erros de autenticação também trazem error_description e o header WWW-Authenticate no padrão OAuth.

JSON

{ "error": "Pedido não encontrado." }

JSON

// 401/403 (autenticação/escopo)
{ "error": "insufficient_scope", "error_description": "Escopo(s) necessário(s): orders:write." }

Status de sucesso

Código	Nome	Quando acontece
200	OK	Requisição bem-sucedida, com o respectivo retorno.
201	Created	Registro criado (ex.: produto, token, webhook).
204	No Content	Sucesso sem corpo (ex.: remoção/revogação).

Status de erro

Código	Nome	Quando acontece
400	Bad Request	Corpo JSON inválido ou parâmetro malformado.
401	Unauthorized	Token ausente, inválido, expirado ou revogado.
403	Forbidden	Escopo insuficiente para esta operação (insufficient_scope).
404	Not Found	Recurso não encontrado (ou pertence a outra loja).
409	Conflict	Conflito de estado — ex.: produto com o mesmo nome já existe.
422	Unprocessable	Validação falhou — verifique os campos obrigatórios.
429	Too Many Requests	Ritmo acima do tolerado — veja Limites de requisição.
502	Bad Gateway	Falha ao consultar um serviço interno (ex.: pedidos). Tente de novo.
5xx	Server Error	Erro interno da Sellit. Use retry com backoff exponencial.

Como reagir

401 — no OAuth, renove com refresh_token antes de reautenticar o lojista; com Token de API da loja, gere um novo token no painel.
403 — o token não tem o escopo exigido. Peça o escopo na autorização (OAuth) ou marque-o ao gerar o Token de API.
409/422 — corrija os dados e reenvie; não faça retry automático (o erro se repete).
429 e 5xx — transitórios: aplique retry com backoff exponencial. Detalhes em Limites de requisição.

Dica: registre o corpo error nos seus logs. As mensagens são descritivas e aceleram o diagnóstico junto ao suporte.