Erros
Envelope, HTTP e o que fazer por código — sem precisar vasculhar cada endpoint.
Toda falha da API devolve um objeto ErrorResponse. Trate pelo campo code (PIX-006, não o título). Validação de campos pode trazer vários itens em errors.
{
"errors": [{
"status": "400",
"code": "REQ-001",
"title": "Requisição inválida",
"description": "A requisição contém dados inválidos",
"action": "Verifique os dados enviados e tente novamente"
}],
"metadata": {
"totalRecords": 1,
"requestDatetime": "2026-06-05T12:00:00Z"
}
}status é string. action é a orientação imediata. metadata.requestDatetime ajuda a cruzar com logs do seu lado.
- 4xx — corrija payload, autenticação ou estado do seller. Retry cego não resolve.
- 409 — conflito de idempotência ou recurso já processado. Repita a requisição original ou use uma
Idempotency-Keynova. - 422 — onboarding, conta PIX ou saldo. O seller ainda não está pronto para aquela operação.
- 429 / 502 / 503 / 504 — retry com backoff.
PIX-006ePIX-016entram aqui.
Falhas de API Key ou token. Corrija a credencial antes de repetir a chamada.
| Código | HTTP | O que significa | O que fazer |
|---|---|---|---|
| AUT-001 | 401 | O token de autenticação é inválido. | Verifique o token e tente novamente. |
| AUT-002 | 401 | O token de autenticação expirou. | Faça login novamente para obter um novo token. |
| AUT-003 | 401 | Email ou senha incorretos. | Verifique as credenciais e tente novamente. |
| AUT-004 | 403 | Sem permissão para este recurso. | Confira o escopo da chave ou contate o administrador. |
| AUT-005 | 401 | A API Key é inválida. | Confira o header X-Api-Key. |
| AUT-006 | 401 | A API Key expirou. | Gere uma nova chave no painel do seller. |
| AUT-007 | 401 | A API Key foi revogada. | Gere uma nova chave no painel do seller. |
| AUT-008 | 401 | A API Key não foi encontrada. | Confira se a chave foi enviada corretamente. |
Cobrança (QR), saque e estorno PIX. 422 costuma ser conta ou saldo; 502/503 vale retry.
| Código | HTTP | O que significa | O que fazer |
|---|---|---|---|
| PIX-004 | 404 | Não há conta de pagamento PIX para este seller. | Confira se o seller concluiu o onboarding PIX. |
| PIX-005 | 422 | A conta PIX do seller não está ativa. | Aguarde a ativação ou contate o suporte. |
| PIX-006 | 502 | Não foi possível gerar o QR Code PIX. | Tente novamente. Se persistir, contate o suporte. |
| PIX-007 | 404 | A transação PIX não foi encontrada. | Verifique o ID da transação. |
| PIX-008 | 422 | Saldo insuficiente para o PIX OUT. | Confira o saldo sacável e tente um valor menor. |
| PIX-009 | 502 | Não foi possível iniciar o PIX OUT. | Tente novamente mais tarde. |
| PIX-010 | 401 | Assinatura do webhook PIX inválida. | Confira o secret configurado no endpoint. |
| PIX-011 | 502 | Não foi possível estornar a transação PIX. | Tente novamente mais tarde. |
| PIX-012 | 409 | Este saque não está na fila de aprovação. | Atualize a lista de pendências. |
| PIX-013 | 422 | Faltam dados do beneficiário para o PIX OUT. | Solicite um novo saque com nome e documento. |
| PIX-014 | 500 | O serviço PIX não está configurado. | Contate o suporte técnico. |
| PIX-015 | 422 | Informe nome e documento de quem vai receber o saque PIX. | Envie a chave PIX e os dados de quem recebe. |
| PIX-016 | 503 | O processamento PIX está em manutenção programada. | Aguarde o término da janela e tente novamente. |
| Código | HTTP | O que significa | O que fazer |
|---|---|---|---|
| PAY-001 | 404 | Pagamento não encontrado. | Verifique o ID do pagamento. |
| PAY-002 | 400 | Método de pagamento não suportado. | Use PIX, cartão de crédito ou boleto. |
| PAY-003 | 400 | Valor do pagamento inválido. | Confira amount e a moeda. |
| PAY-004 | 409 | Este pagamento já foi processado. | Não reenvie a mesma cobrança. |
| PAY-005 | 410 | O pagamento expirou. | Crie um novo pagamento. |
| PAY-006 | 410 | O pagamento foi cancelado. | Crie um novo pagamento. |
| PAY-007 | 202 | O pagamento ainda está em processamento. | Aguarde e consulte o status. |
| PAY-008 | 400 | Taxas aplicadas ao pagamento são inválidas. | Revise o plano de taxas do seller. |
| PAY-009 | 500 | Não foi possível recuperar o pagamento. | Tente novamente mais tarde. |
| TRX-001 | 404 | Transação não encontrada. | Verifique o ID da transação. |
| TRX-002 | 400 | Status incompatível com esta operação. | Consulte o status atual antes de repetir. |
| TRX-003 | 400 | A transação foi recusada pelo emissor. additionalInfo traz declineCode, declineMessage e, quando o banco informa, issuer. | Peça ao comprador para contatar o emissor do cartão ou usar outro cartão. |
| TRX-004 | 409 | Há um chargeback em andamento. | Acompanhe no painel do seller. |
| TRX-005 | 409 | O estorno já foi processado. | Não solicite o mesmo estorno novamente. |
| TRX-006 | 400 | Configuração de split inválida. | Revise os participantes e percentuais. |
| TRX-007 | 400 | Número de parcelas acima do limite. | Use menos parcelas. |
| TRX-008 | 400 | Rateio entre participantes inválido. | A soma do split deve bater com o valor da venda. |
| TRX-009 | 400 | Valor de estorno maior que o saldo da transação. | Estorne no máximo o valor restante. |
| TRX-010 | 409 | Idempotency-Key já usada com outro payload. | Repita a requisição original ou use uma chave nova. |
| TRX-011 | 400 | Informe exatamente uma fonte de comprador. | Envie buyerId, buyer ou customer — nunca mais de um. |
| TRX-012 | 400 | Informe exatamente uma fonte de cartão. | Envie cardToken ou os dados do cartão, não os dois. |
| TRX-013 | 429 | Muitas tentativas de pagamento em pouco tempo. | Aguarde alguns minutos antes de tentar de novo. |
| TRX-014 | 422 | Nenhum adquirente de cartão elegível para esta venda. | Confira o onboarding de cartão do seller. |
| TRX-015 | 404 | Política de roteamento não encontrada. | Verifique o identificador informado. |
| TRX-016 | 400 | Regra de roteamento inválida. | Revise prioridade, condições e destino. |
| TRX-017 | 422 | A transação ainda não tem identificador no processador. | Aguarde a confirmação ou contate o suporte. |
| TRX-018 | 400 | Operação inválida para este método de pagamento. | Confira se a transação aceita estorno ou captura. |
| TRX-019 | 422 | O cardToken é inválido ou expirou. | Tokenize o cartão novamente. |
| TRX-020 | 404 | Evento de cartão sem transação correspondente. | O evento será reprocessado automaticamente. |
| TRX-021 | 400 | Evento de cartão sem identificadores obrigatórios. | Verifique o payload recebido. |
| Código | HTTP | O que significa | O que fazer |
|---|---|---|---|
| CHK-001 | 404 | Sessão de checkout não encontrada. | Inicie um novo checkout. |
| CHK-002 | 410 | A sessão de checkout expirou. | Inicie um novo checkout. |
| CHK-003 | 400 | O carrinho está vazio. | Adicione itens antes de confirmar. |
| CHK-004 | 400 | Dados de pagamento incompletos. | Preencha os campos obrigatórios. |
| CHK-005 | 400 | Cartão precisa ser tokenizado antes do confirm. | Conclua a tokenização PCI e envie o cardToken. |
| CHK-006 | 400 | A transação exige 3DS concluído. | Complete setup → authenticate → challenge antes do confirm. |
| CHK-007 | 400 | Valor da cobrança não informado. | Envie um amount válido. |
| CHK-008 | 400 | Valor abaixo do mínimo permitido. | Aumente o valor da cobrança. |
| CHK-010 | 403 | Transação recusada pelo antifraude. | Revise os dados ou use outro método. |
| CHK-011 | 422 | Transação em análise antifraude. | Aguarde a revisão. |
| CHK-012 | 400 | Autenticação 3DS recusada pela emissora. | Tente outro cartão ou método. |
| CHK-013 | 401 | clientSecret da sessão inválido ou ausente. | Use o clientSecret devolvido ao criar a sessão. |
| CHK-014 | 403 | Origem do browser fora da allowlist da publishable key. | Cadastre o domínio nas configurações da chave. |
| Código | HTTP | O que significa | O que fazer |
|---|---|---|---|
| BYR-001 | 404 | Comprador não encontrado. | Verifique o buyerId. |
| BYR-002 | 409 | CPF/CNPJ já cadastrado para outro comprador deste seller. | Reutilize o comprador existente neste seller. |
| BYR-003 | 409 | Email já cadastrado para outro comprador deste seller. | Use outro email ou o comprador existente neste seller. |
| BYR-004 | 400 | Dados do comprador inválidos. | Revise nome, documento e contato. |
| BYR-005 | 403 | Comprador inativo. | Ative o comprador ou use outro. |
| BYR-006 | 403 | Comprador excedeu o limite de compras. | Aguarde o próximo período. |
| VLD-001 | 400 | CPF inválido. | Envie um CPF com dígitos verificadores corretos. |
| VLD-002 | 400 | CNPJ inválido. | Envie um CNPJ com dígitos verificadores corretos. |
| VLD-003 | 400 | Email inválido. | Use um endereço de email válido. |
| VLD-004 | 400 | Telefone inválido. | Use o formato (DDD) 99999-9999. |
| VLD-005 | 400 | CEP inválido. | Confira o CEP. |
| VLD-006 | 400 | Chave Pix inválida. | Confira CPF, CNPJ, email, telefone ou EVP. |
| VLD-007 | 400 | Código de banco inválido. | Use um COMPE válido (ex.: 001, 237, 341). |
| VLD-008 | 400 | Campo obrigatório ausente. | Preencha todos os campos exigidos. |
| VLD-009 | 400 | Formato de campo incorreto. | Ajuste o payload e tente novamente. |
| VLD-010 | 400 | Valor fora do intervalo permitido. | Use um valor dentro dos limites da API. |
Estes códigos bloqueiam cobrança até o cadastro do seller estar pronto.
| Código | HTTP | O que significa | O que fazer |
|---|---|---|---|
| SLR-001 | 404 | Seller não encontrado. | Verifique o sellerId. |
| SLR-003 | 403 | Seller ainda não foi aprovado. | Aguarde a análise do cadastro. |
| SLR-004 | 403 | Seller suspenso. | Contate o suporte. |
| SLR-005 | 403 | Seller reprovado. | Contate o suporte. |
| SLR-015 | 422 | Seller ainda não pode transacionar. | Conclua onboarding, KYC, termo e tabela de preço. |
| KYC-001 | 422 | Verificação de identidade ainda não aprovada. | Conclua o KYC antes de cobrar. |
| Código | HTTP | O que significa | O que fazer |
|---|---|---|---|
| WBH-001 | 400 | Configuração do webhook inválida. | Confira a URL HTTPS e os eventTypes. |
| WBH-002 | 500 | Não foi possível enviar o webhook. | Confira se o endpoint está acessível. |
| WBH-003 | 500 | O endpoint do webhook não respondeu. | Garanta um 2xx em poucos segundos. |
| WBH-004 | 400 | Falha ao interpretar o payload do webhook. | Envie JSON no formato esperado. |
| WBH-005 | 401 | Assinatura do webhook inválida. | Valide X-Reborn-Signature com o secret da criação. |
| Código | HTTP | O que significa | O que fazer |
|---|---|---|---|
| SUB-001 | 404 | Plano de assinatura não encontrado. | Verifique o ID do plano. |
| SUB-002 | 422 | Plano arquivado — não aceita novas assinaturas. | Use um plano ativo. |
| SUB-003 | 404 | Assinatura não encontrada. | Verifique o ID da assinatura. |
| SUB-004 | 409 | Assinatura já cancelada. | Não altere uma assinatura encerrada. |
| SUB-005 | 400 | Assinatura no cartão exige cardToken. | Tokenize o cartão e envie o token. |
| SUB-006 | 409 | Operação só vale para assinatura suspensa. | Confira o status atual. |
| SUB-007 | 502 | Falha ao cobrar a assinatura. | Tente novamente mais tarde. |
| SUB-008 | 400 | Método não suportado para assinaturas. | Use CREDIT_CARD, DEBIT_CARD ou PIX. |
| CPN-001 | 404 | Cupom não encontrado. | Verifique o código ou ID. |
| CPN-002 | 409 | Já existe um cupom ativo com este código. | Escolha outro código. |
| CPN-003 | 422 | Cupom inativo. | Ative o cupom ou use outro. |
| CPN-004 | 422 | Cupom expirado. | Use outro cupom. |
| CPN-005 | 422 | O período do cupom ainda não começou. | Aguarde a data de início. |
| CPN-006 | 422 | Limite global de uso do cupom atingido. | Use outro cupom. |
| CPN-007 | 422 | Este comprador já usou o cupom no limite. | Use outro cupom. |
| CPN-008 | 422 | Cupom não vale para este link de pagamento. | Confira as restrições do cupom. |
| CPN-009 | 422 | Valor da compra abaixo do mínimo do cupom. | Aumente o valor ou remova o cupom. |
API de companies e planos de taxa. Quedas aqui costumam bloquear split PIX ou precificação.
| Código | HTTP | O que significa | O que fazer |
|---|---|---|---|
| FEE-001 | 404 | Plano de taxas não encontrado. | Verifique o ID do plano. |
| FEE-002 | 422 | Plano ainda sem tabela de preço. | Configure a tabela antes de vincular sellers. |
| FEE-003 | 400 | Tipo do plano não corresponde ao esperado. | Confira se o plano é COMPANY ou REBORN. |
| FEE-004 | 500 | Plano padrão de onboarding não está configurado. | Contate o suporte. |
| FEE-005 | 404 | Plano interno da company não encontrado. | Verifique se o plano pertence à company. |
| FEE-006 | 422 | A company não tem plano de custo para calcular a taxa. | Configure os planos PIX e cartão da company. |
| FEE-007 | 422 | Com base no plano de taxas, este valor não cobre todos os custos. | Informe um valor igual ou maior que o mínimo do plano. |
| FEE-008 | 422 | A conta PIX compartilhada não está configurada. | Contate o suporte. |
| Código | HTTP | O que significa | O que fazer |
|---|---|---|---|
| REQ-001 | 400 | A requisição contém dados inválidos. | Revise o JSON e os campos obrigatórios. |
| REQ-002 | 405 | Método HTTP não suportado neste path. | Use GET, POST, PUT ou DELETE conforme a referência. |
| REQ-003 | 415 | Content-Type inválido. | Envie application/json. |
| REQ-004 | 413 | Payload maior que o permitido. | Reduza o tamanho da requisição. |
| REQ-005 | 400 | Parâmetros da requisição inválidos. | Confira query e path params. |
| REQ-006 | 400 | JSON malformado. | Valide o body antes de enviar. |
| REQ-007 | 404 | Recurso não encontrado. | Confira a URL. |
| INT-003 | 503 | Serviço de pagamento temporariamente indisponível. | Faça retry com backoff. |
| INT-004 | 504 | Tempo limite de resposta excedido. | Faça retry com backoff. |
| INT-005 | 400 | Erro de validação na integração. | Revise os dados enviados. |
| INT-006 | 500 | Falha de autenticação com serviço externo. | Tente novamente ou contate o suporte. |
| INT-007 | 429 | Limite de requisições excedido. | Aguarde e respeite o rate limit. |
| INT-008 | 500 | Não foi possível processar o pagamento. | Tente novamente mais tarde. |
| INT-010 | 500 | Erro interno ao processar a operação. | Tente novamente mais tarde. |
| INT-011 | 503 | Pagamentos internacionais indisponíveis. | Contate o suporte. |
| INT-012 | 503 | A região de pagamento não está configurada. | Confira a moeda da transação. |
| SRV-001 | 500 | Erro interno do servidor. | Tente novamente mais tarde. |
| SRV-002 | 503 | Serviço temporariamente indisponível. | Faça retry com backoff. |
| SRV-003 | 500 | Falha ao persistir dados. | Tente novamente mais tarde. |
| SRV-004 | 504 | Tempo limite ao persistir dados. | Tente novamente mais tarde. |
| SRV-005 | 500 | Falha em serviço interno de sessão. | Tente novamente mais tarde. |
| SRV-006 | 500 | Erro ao processar o arquivo enviado. | Verifique o arquivo e tente novamente. |
| SRV-007 | 500 | Erro ao processar a imagem enviada. | Verifique a imagem e tente novamente. |
Métodos, paths e schemas estão na API Reference. Este guia cobre o que fazer quando a resposta não é 2xx.