Erros e boas práticas
O formato de toda resposta, o que cada status significa e quando tentar de novo.
https://app.reton.com.br/api/v1Atualizado em 30 de setembro de 2026Navegar na API
Toda resposta da API — de sucesso ou de erro — vem no mesmo "envelope". Olhe primeiro o success: se for true, o resultado está em data; se for false, o motivo está em error.
Os comandos desta página saem prontos para copiar. A chave fica só nesta aba — não é salva nem enviada.
O formato de toda resposta
| Campo | O que é |
|---|---|
success | true deu certo; false deu erro. |
data | O resultado (só quando success é true). |
error.code | Código do erro, para o seu programa decidir o que fazer (ex.: CONFLICT). Não muda. |
error.message | Explicação em português, para mostrar ou registrar no log. O texto pode mudar — não compare com ele. |
error.details | Quando existe, uma lista com o detalhe (ex.: qual campo está errado). |
meta.requestId | Identificador da chamada. Mande para o suporte quando algo der errado — com ele achamos a chamada. |
{ "success": true, "data": { "id": "con_LC4dQtpwbrLudiRS", "…": "…" }, "meta": { "requestId": "req_V1StGXR8Z5jdHi6B" }}{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Erro de validação nos dados enviados.", "details": [ { "field": "valor", "message": "valor é obrigatório e deve ser numérico", "code": "invalid_type" } ] }, "meta": { "requestId": "req_V1StGXR8Z5jdHi6B" }}O que cada status significa
| Status | Significa | Tentar de novo? |
|---|---|---|
200 / 201 | Deu certo (201 = algo foi criado). | — |
400 | O pedido está errado: campo faltando, formato inválido, regra de negócio (ex.: saldo insuficiente). Leia error.message. | Não. Corrija antes. |
401 | Chave ausente, errada ou revogada. | Não. Veja Autenticação. |
403 | A conta não está no plano Pro. | Não. |
404 | O que você pediu não existe na sua conta. | Não. |
409 | Conflito com o que já existe (cliente repetido, venda já estornada…). error.code diz qual. | Não. Trate o caso. |
422 | O pedido está certo, mas não pode ser feito agora (ex.: desativar a única loja). | Não. |
500 | Falha do nosso lado. | Sim, depois de alguns segundos. |
| Timeout / sem resposta | A rede caiu no meio do caminho — a chamada pode ou não ter sido gravada. | Sim, com os mesmos dados (veja abaixo). |
Códigos de erro
error.code | Status | Quando |
|---|---|---|
VALIDATION_ERROR | 400 / 422 | Dado inválido ou regra de negócio. Em erro de campo, details traz field, message e code. |
UNAUTHORIZED | 401 | Problema com a chave. |
FORBIDDEN | 403 | Plano sem API. |
NOT_FOUND | 404 | Não encontrado. |
CONFLICT | 409 | Já existe (ex.: cliente com o mesmo celular — o id dele vem em details). |
INTERACAO_DUPLICADA | 409 | Venda idêntica no mesmo dia, sem codigoItem. |
INTERACAO_NAO_ENCONTRADA | 404 | Estorno de uma venda que não existe. |
INTERACAO_JA_ESTORNADA | 409 | Estorno de uma venda já estornada. |
ESTORNO_PONTOS_UTILIZADOS | 409 | O cliente já usou o que a venda gerou. |
SEM_RECOMPENSA | 409 | Estorno só da pontuação, numa venda que não pontuou. |
ESTORNO_RECOMPENSA_BLOQUEADO | 409 | Estorno só da pontuação que não pode ser feito (já usada ou já estornada). |
INTERNAL_ERROR | 500 | Falha nossa. Tente de novo. |
Reenviar sem duplicar
Rede cai. Quando a chamada de venda não tem resposta, você não sabe se ela entrou. A regra é simples: mande de novo, com os mesmos dados e o mesmo codigoItem. Se já tinha entrado, o Reton devolve a original (200, "duplicada": true) e não soma nada duas vezes — nem pontos, nem o uso de cashback.
- Espere um pouco entre as tentativas (2s, depois 4s, depois 8s…) e desista depois de umas 5.
- Guarde num log o
requestIddas chamadas que falharam. - No cadastro de cliente, o reenvio também é seguro: a segunda chamada volta
409com o id de quem já foi criado.
Limites de uso
Hoje não há um limite fixo de chamadas por segundo — mas mande as vendas conforme acontecem, uma por vez, em vez de milhares em rajada. Para trazer o histórico inteiro de uma vez, fale com o suporte: a importação por planilha ou a integração assistida é o caminho certo.
As vendas contam na franquia de transações do seu plano, do mesmo jeito que as registradas no painel.
Isso foi útil?
Ainda precisa de ajuda?
Não achou o que procurava? A gente responde de gente pra gente.