Códigos de erros

Use parameter para identificar o erro. O campo traz o identificador técnico da condição; message descreve o problema. Baseie as regras da integração em parameter, pois o texto da mensagem pode mudar ou incluir detalhes variáveis.

Combine o identificador com o código HTTP e a operação chamada. O mesmo identificador pode aparecer com códigos HTTP diferentes. Erros de validação e algumas respostas do Checkout usam outros formatos, descritos em Respostas e Convenções da API.

Autenticação e autorização

As chamadas autenticadas da integração usam o header api_key. Confira Chaves e Autenticação da API.

Identificador	HTTP	Quando ocorre	Como resolver
`auth.api_key_not_found`	401	O header esperado não contém a chave.	Envie `api_key` pelo servidor da integração.
`auth.invalid_api_key`	401	A chave não identifica uma empresa.	Confira a chave e o ambiente. Se ela foi redefinida, atualize a integração.
`company.inactive`	401	A empresa identificada pela chave está inativa.	Verifique a situação da empresa no BackOffice com a equipe responsável.
`company.ip_access_denied`	403	A origem da chamada não atende à restrição de IP habilitada para a empresa.	Confira o IP de saída do servidor e as regras de acesso da empresa.

Empresas e configurações

Identificador	HTTP	Quando ocorre	Como resolver
`company.has_no_active_contract_provider`	400	A criação de Vendedor não encontra contrato ativo da empresa para o provedor exigido.	Confira a habilitação contratual da empresa antes de criar o Vendedor.
`company.payment_method_no_active`	400	O meio de pagamento solicitado não está ativo.	Use um meio habilitado ou revise sua ativação.
`company.not_allowed_more_than_one_payment`	403	O fluxo recebeu mais de um pagamento e a empresa não está habilitada para isso.	Ajuste a solicitação à configuração de pagamentos da empresa.
`company.split_not_allowed`	401	A empresa não está habilitada para a operação de Split.	Confira a habilitação de marketplace/Split. Este erro de configuração usa 401 no fluxo implementado.

Vendas (`charge`)

Identificador	HTTP	Quando ocorre	Como resolver
`charge.not_found`	404; 400 ao excluir Split	A Venda não foi localizada. No reembolso de Split, o mesmo erro também pode indicar que o próprio Split não existe.	Confira o UUID, a empresa e o ambiente; use Consultar uma venda.
`charge.invalid_status`	400	O estado da Venda não permite a ação solicitada.	Consulte o estado atual e as pré-condições da operação.
`charge.invalid_type`	400	O tipo da Venda não é aceito pelo fluxo.	Confira o `type` e escolha a operação correspondente.
`charge.max_attempts_reached`	400	A Venda atingiu seu limite de tentativas de pagamento.	Interrompa as tentativas para essa Venda e investigue as recusas anteriores.
`charge.due_date_before_actual_date`	400	A edição propõe vencimento anterior ao permitido pelo fluxo.	Revise a data e as regras de Editar venda.
`charge.amount_less_than_paid`	400	O novo valor é menor que o valor já pago.	Consulte os pagamentos antes de ajustar o valor da Venda.
`charge.with_split_cannot_update_amount`	400	A edição tenta alterar o valor de uma Venda com Split.	Preserve o valor e confira as operações disponíveis para essa Venda.
`charge.tokenization_cannot_refunded`	400	O fluxo de reembolso recebeu uma Venda de tokenização.	Confira o tipo e localize a operação financeira que pretende reembolsar.
`charge.amount_greater_than_charge_amount`	400	O valor de reembolso solicitado supera o valor da Venda no fluxo validado.	Recalcule o valor e confira os reembolsos anteriores.

Transações (`transaction`)

Identificador	HTTP	Quando ocorre	Como resolver
`transaction.not_found`	404; 400 em resposta específica do provedor na captura	A Transação não foi localizada ou o provedor informou essa condição durante a captura.	Confira o UUID e a empresa; use Consultar uma transação.
`transaction.invalid_status`	400	O estado da Transação não permite a ação. No reembolso de Split, também pode indicar um estado incompatível da Venda.	Consulte a Venda e a Transação; avalie cada estado separadamente.
`transaction.invalid_payment_method`	400	O meio de pagamento é incompatível com a operação.	Confira o meio e a referência da operação de captura, cancelamento ou reembolso.
`transaction.already_captured`	409	A captura de cartão já foi realizada.	Consulte a Transação e não envie nova captura para repetir o efeito.
`transaction.already_canceled`	409	A Transação já foi cancelada.	Consulte o resultado do cancelamento existente.
`transaction.already_expired`	409	O cancelamento de Pix encontra uma Transação já expirada.	Consulte a Transação e a Venda; repetir o cancelamento não altera a expiração.
`transaction.already_processing_refund`	400	Já há processamento de reembolso para a Transação.	Acompanhe o reembolso em andamento antes de solicitar outro.
`transaction.invalid_capture_amount`	400	O valor solicitado para captura não atende à validação do fluxo.	Confira o valor autorizado e os limites da captura.
`transaction.manual_capture_contract_not_authorized`	400	O contrato não permite captura manual.	Confira a configuração contratual e a modalidade de captura utilizada.
`transaction.capture_err`	400	O provedor informou falha durante a captura.	Consulte a Transação e preserve a correlação para investigar com o suporte.
`transaction.amount_greater_than_transaction`	400	O reembolso solicitado supera o valor da Transação.	Corrija o valor e confira qual Transação está sendo reembolsada.
`transaction.amount_greater_than_paid_amount`	400	O valor solicitado supera o valor pago validado pelo fluxo.	Consulte o valor pago e os reembolsos antes de recalcular.
`transaction.cannot_refund_boleto_payment`	400	O fluxo de reembolso chamado não aceita pagamento por Boleto.	Consulte a referência de Reembolsos de Pix e Boleto para o fluxo aplicável.
`transaction.gateway_refund_error`	400	Houve falha na solicitação de reembolso ao gateway de pagamento.	Verifique o estado da Transação e do reembolso antes de reenviar; o HTTP 400 não comprova erro de preenchimento.

Pagamentos

Uma recusa de pagamento pode ser representada no estado da Transação, mesmo quando a requisição HTTP teve sucesso. Não há um identificador parameter único que represente toda recusa. Use os campos de resultado descritos em Solução de Problemas e Boas Práticas.

Identificador	HTTP	Quando ocorre	Como resolver
`payment.pay_more_than_charge_amount`	400	No Checkout, o valor do pagamento supera o permitido para a Venda.	Consulte o saldo da Venda e ajuste o valor enviado.

Checkout e SmartForm

Identificador	HTTP	Quando ocorre	Como resolver
`checkout.not_found`	404	O Checkout não foi localizado.	Confira o link ou identificador usado.
`checkout.expired`	400	O fluxo encontra o Checkout expirado.	Consulte a Venda e solicite um link válido à equipe responsável.
`checkout.is_expired`	400	Outra verificação de validade encontra expiração.	Investigue a validade do link; preserve esse identificador distinto no tratamento.
`checkout.no_active`	400	O Checkout está inativo.	Confirme o estado da Venda e do link antes de reiniciar o pagamento.
`checkout.template_not_found`	400 na gestão/consulta de templates; 404 na resolução do template de um Checkout/link	O template informado não foi localizado para o fluxo.	Confira o UUID e se o template pertence à empresa da operação.
`checkout.template_no_active`	400	O fluxo de pagamento encontra um template inativo.	Use um template ativo e confira a configuração do Checkout.
`checkout.template_inactive`	400	A criação da Venda recebeu um template inativo.	Ative o template ou escolha outro antes de criar o link.
`checkout.smarform_disabled`	400	O SmartForm está desabilitado para o Checkout.	Confira as configurações de cartão e SmartForm. A API retorna o identificador com a grafia `smarform`.
`checkout.without_payment_settings`	400	Faltam configurações de pagamento exigidas pelo fluxo.	Confira a configuração da Venda/Checkout e os meios habilitados.
`checkout.smartform_limit_exceeded`	429	O limite de tentativas da sessão de SmartForm foi atingido.	Interrompa as tentativas e investigue o resultado do pagamento. Não contorne o limite criando sessões em sequência.

Split de pagamento e Vendedores

Confira os campos de entrada na referência de Adicionar split na venda.

Identificador	HTTP	Quando ocorre	Como resolver
`charge.split_already_created`	409	A Venda já tem Split cadastrado.	Consulte o Split existente antes de enviar nova criação.
`charge.split_not_found`	404	A consulta direta por UUID não encontra o Split.	Confira o UUID do Split; ele é diferente do UUID da Venda.
`charge.cannot_split_tokenization`	400	A criação tenta aplicar Split a uma Venda de tokenização.	Confira o tipo da Venda e use o fluxo de Split de uma Venda compatível.
`charge.split_greater_than_charge_amout`	400	A validação encontra total de participações igual ou superior ao valor da Venda.	Recalcule a distribuição. Preserve a grafia `amout` no tratamento do identificador.
`charge.split_exceeded_maximum_percentage`	400	Um percentual ou a soma dos percentuais supera o máximo permitido.	Revise o tipo de Split e os percentuais enviados.
`charge.split_exceeded_minimum_percentage`	400	Em cartão, o percentual não atende ao mínimo verificado pelo fluxo.	Confira a escala do percentual e o valor na referência da operação.
`charge.split_exceeded_minimum_amount`	400	O valor calculado de uma participação, inclusive percentual, não atende ao mínimo.	Confira a unidade monetária e o resultado do cálculo da participação.
`charge.split_seller_cannot_duplicate`	400	O mesmo Vendedor aparece mais de uma vez na distribuição.	Remova a duplicidade de `seller_uuid`.
`charge.split_seller_cannot_set_amount`	400	Uma regra `REMAINING` informa `amount` diferente de zero.	Corrija o valor enviado para a regra de remanescente.
`charge.cannot_have_more_than_one_remaining`	400	Há mais de uma regra de remanescente.	Mantenha a distribuição com uma única regra de remanescente.
`seller.not_found`	404	Um Vendedor informado não foi localizado.	Confira `seller_uuid` e a empresa; use Consultar um Vendedor.
`seller.invalid_status`	400	O estado do Vendedor é incompatível com a operação.	Consulte o cadastro e resolva a situação do Vendedor antes de repetir.
`seller.exceeded_maximum_number_split`	400	A quantidade de participantes excede a validação do fluxo.	Reduza a quantidade e confira o limite da operação; não deduza o limite apenas do texto da mensagem.
`charge.cannot_refund_split_primary_only`	400	A solicitação tenta reembolsar somente a participação principal em um fluxo que não permite isso.	Confira a composição e a referência de reembolso do Split.
`charge.amount_greater_than_split_amount`	400	O reembolso supera o saldo disponível da participação ou esse saldo já está esgotado.	Consulte o Split e os reembolsos anteriores antes de ajustar o valor.

Limite de participantes: A confirmar

A mensagem de seller.exceeded_maximum_number_split cita máximo de cinco, mas a validação consultada rejeita cinco ou mais itens. Não use essa mensagem para deduzir que cinco participantes serão aceitos; confirme o limite contratual do fluxo.

Idempotência

O header é documentado em Criar venda, Pagar venda em aberto e Simular pagamento Pix/Boleto, esta última somente no Sandbox. Consulte também as convenções de idempotência.

Identificador	HTTP	Quando ocorre	Como resolver
`idempotency_key.invalid`	400	A chave não vazia não é um UUID válido.	Envie um UUID válido no header `Idempotency-Key`.
`idempotency_key.payload_mismatch`	409	A chave já foi associada a outro payload no mesmo escopo.	Para repetir a mesma operação, preserve chave e dados. Use outra chave somente para uma nova operação intencional.
`idempotency_key.processing`	409	A solicitação com essa chave ainda está em processamento.	Aguarde e consulte o estado. Não envie em paralelo outra chave para o mesmo pagamento.
`idempotency_key.failed`	409	A tentativa anterior com essa chave foi marcada como falha.	Confira o resultado financeiro antes de decidir por uma nova tentativa; a mesma chave não reinicia esse processamento.
`idempotency_key.result_not_found`	409	O processamento registrado não permite recuperar o resultado esperado.	Consulte a Venda e acione o suporte com a correlação. Evite criar outra operação às cegas.
`idempotency_key.create_error`	400	Não foi possível registrar o controle de idempotência.	Investigue com a correlação e confira o estado antes de tentar novamente.

Validação de parâmetros

Identificador	HTTP	Quando ocorre	Como resolver
`system.invalid_param_uuid`	400	Um identificador da URL não pôde ser interpretado como UUID.	Confira o parâmetro de caminho e copie o UUID completo do recurso.
`system.invalid_body`	400	O tratamento da requisição identificou corpo inválido.	Revise JSON, tipos e campos do endpoint.

A validação de campos também pode responder HTTP 400 com errors[], sem parameter. Cada item contém field e message. Corrija os campos indicados; não tente procurar o texto da validação como identificador deste catálogo.

Falhas internas e comunicação

Identificador	HTTP	Quando ocorre	Como resolver
`system.internal_error`	500	O tratamento comum recebeu uma falha interna sem resposta de domínio específica.	Registre a correlação, consulte o recurso se houver efeito financeiro e acione o suporte.
`system.err_parse_body`	400	Um fluxo não conseguiu interpretar ou serializar os dados necessários.	Confira o JSON; se estiver correto, envie endpoint e correlação ao suporte.
`system.error_external_communication`	400 em operações como captura/reembolso; 503 em criação de Transação de cartão	Ocorreu falha de comunicação com um serviço externo.	Consulte a Venda e a Transação antes de reenviar; preserve seus UUIDs e a correlação.
`system.error_external_response`	400 nos fluxos observados	O serviço externo retornou resposta que o fluxo não conseguiu tratar.	Registre endpoint, HTTP e correlação; confira o estado financeiro e encaminhe o diagnóstico ao suporte.

Erros internos e de provedor nem sempre retornam HTTP 5xx. Para investigar uma resposta inesperada, siga o procedimento de diagnóstico e reenvio seguro.