Baixar (.md)OpenAPI

Erros

Todo erro vem no mesmo envelope:

{
  "erro": {
    "codigo": "COBRANCA_PENDENTE_EXISTE",
    "mensagem": "Já existe uma cobrança aberta neste caixa. Cancele ou use cancelarPendenteAnterior.",
    "detalhes": { "cobrancaId": "…" },
    "requestId": "req_7Qm…"
  }
}

Decida pelo codigo (estável), não pela mensagem (pode mudar de texto). Guarde o requestId: é o que o suporte precisa para achar a chamada.

Todos os códigos

HTTP Código Mensagem
400 VALIDACAO Um ou mais campos são inválidos.
400 CAMPO_DESCONHECIDO O corpo tem campos que esta rota não aceita.
400 IDEMPOTENCY_KEY_OBRIGATORIA Envie o cabeçalho Idempotency-Key (até 128 caracteres).
400 CENARIO_SO_EM_TESTE O cabeçalho Moeda-Nobre-Teste-Cenario só vale com chave de teste.
400 CENARIO_INVALIDO Cenário de teste desconhecido.
401 CHAVE_INVALIDA A chave não existe ou está errada. Confira se copiou inteira.
401 CHAVE_REVOGADA Esta chave foi revogada. Crie uma nova no portal.
401 PARCEIRO_SUSPENSO O acesso da sua empresa está suspenso. Fale com a TribeX.
401 PRODUCAO_NAO_LIBERADA Sua conta ainda só usa chaves de teste. Conclua a homologação.
401 APLICATIVO_DESATIVADO O aplicativo desta chave está desativado.
403 CHAVE_EM_NAVEGADOR A chave foi usada a partir de um navegador. Ela deve ficar no servidor.
404 PDV_NAO_ENCONTRADO Ponto de venda não encontrado.
404 COBRANCA_NAO_ENCONTRADA Cobrança não encontrada.
404 RECURSO_NAO_ENCONTRADO Recurso não encontrado.
405 METODO_NAO_PERMITIDO Método não permitido nesta rota.
409 COBRANCA_PENDENTE_EXISTE Já existe uma cobrança aberta neste caixa. Cancele ou use cancelarPendenteAnterior.
409 COBRANCA_NAO_PENDENTE A cobrança não está mais pendente.
409 REQUISICAO_EM_ANDAMENTO Uma requisição com esta Idempotency-Key ainda está em andamento. Repita em 1 segundo.
409 PDV_JA_ATIVO Este caixa já está ativo neste aplicativo.
410 CODIGO_ATIVACAO_EXPIRADO O código de ativação expirou. Peça um novo ao gerente da loja.
413 CORPO_GRANDE O corpo da requisição passa de 64 KB.
415 CONTENT_TYPE Envie o corpo como application/json.
422 IDEMPOTENCY_CONFLITO Você reutilizou uma Idempotency-Key com dados diferentes.
422 PDV_INATIVO O gerente da loja desativou este caixa.
422 LOJA_INATIVA A loja está inativa na Moeda Nobre.
422 VINCULO_REVOGADO A loja desconectou o seu sistema.
422 CODIGO_ATIVACAO_INVALIDO Código de ativação inválido.
429 LIMITE_EXCEDIDO Limite de requisições excedido. Aguarde e tente de novo.
500 ERRO_INTERNO Erro interno. Informe o requestId ao suporte.
503 INDISPONIVEL Serviço temporariamente indisponível. Tente de novo em instantes.

O que fazer em cada caso

Código O que fazer
CHAVE_INVALIDA A chave não existe ou está errada. Confira se copiou inteira e se é do ambiente certo.
CHAVE_REVOGADA Crie uma chave nova no portal e troque no servidor.
PRODUCAO_NAO_LIBERADA Sua conta ainda só usa chaves de teste. Conclua a homologação e peça a liberação.
PARCEIRO_SUSPENSO O acesso da sua empresa está suspenso. Fale com a TribeX.
PDV_INATIVO O gerente da loja desligou este caixa. Mostre isso ao operador — não fique repetindo.
LOJA_INATIVA A loja está inativa na Moeda Nobre.
VINCULO_REVOGADO A loja desconectou o seu sistema. Só volta com um código novo do gerente.
COBRANCA_PENDENTE_EXISTE Já há uma cobrança aberta neste caixa (id em detalhes.cobrancaId). Cancele-a ou mande cancelarPendenteAnterior: true.
COBRANCA_NAO_PENDENTE A cobrança mudou de estado (detalhes.statusAtual). Se for PAGA, o cliente pagou: siga com a venda.
IDEMPOTENCY_CONFLITO Você reutilizou uma Idempotency-Key com dados diferentes. Use uma chave nova para uma cobrança nova.
REQUISICAO_EM_ANDAMENTO A mesma Idempotency-Key ainda está sendo processada. Repita depois do Retry-After (1 s).
CHAVE_EM_NAVEGADOR A chave foi usada a partir de um navegador. Ela deve ficar no servidor.
LIMITE_EXCEDIDO Espere o Retry-After (em segundos) e tente de novo.
ERRO_INTERNO / INDISPONIVEL Tente de novo com espera crescente (1 s, 2 s, 4 s…). Em POST /cobrancas, repita com a mesma Idempotency-Key — nunca cria duas.

Quando repetir

  • Repita (com espera crescente): 429, 500, 503, 409 REQUISICAO_EM_ANDAMENTO e falhas de rede.
  • Não repita a mesma chamada: os demais 4xx. Eles só mudam se algo mudar (o operador, a loja, o seu código). A homologação confere isso: depois de um 422 PDV_INATIVO, no máximo 3 chamadas iguais no minuto seguinte.