Códigos de erro

Ao fazer requisições para a API de Pedidos, parâmetros incorretos podem gerar erros que impedem o fornecimento de uma resposta com os dados esperados. Nesse caso, erros serão retornados como resposta à sua requisição para ajudá-lo a entender o problema.

Nesta página também são apresentadas as listas de erros relacionadas aos endpoints Consultar taxas de uma transação e Validar e armazenar um cartão no PagBank. Esses endpoints não pertencem diretamente à API de Pedidos, mas fornecem serviços auxiliares ao processo de criação e pagamento de pedidos.

Tratamento de erros

Você receberá um HTTP Status 400, 401, 403, 404 ou 409 como resposta quando não conseguirmos prosseguir com a operação. Nesse caso você deve verificar o conteúdo enviado e corrigir o erro antes de realizar uma nova requisição. No corpo da resposta você encontrará informações sobre o erro enfrentado e sobre o seu tipo.

É importante destacar que existem dois tipos de resposta pela API Pagbank quando um erro é encontrado. O tipo de resposta retornado dependerá se o erro foi encontrado em algum parâmetro do objeto Order ou do objeto Charge. Cada uma dos possíveis padrões de resposta são apresentados a seguir.

{
  "code": "CODIGO_IDENTIFICADOR_DO_ERRO",
  "description": "descrição detalhada do erro",
  "parameter_name": "nome_do_parameto_que_gerou_o_erro_(opcional)"
}
{
    "error_messages": [
        {
            "code": "40001",
            "description": "required_parameter",
            "parameter_name": "payment_method.capture"
        }
    ]
}

Lista de erros da API de Pedidos

Os códigos de erro apresentados na tabela abaixo podem ocorrer durante a interação com a API de Pedidos do PagBank. Esses códigos são acompanhados por pequenas descrições. Consulte a tabela abaixo para obter mais informações sobre cada código de erro e o respectivo cenário.

Código Descrição Cenário HTTP Status
40001 required_parameter Parâmetro obrigatório não foi informado. 400
40002 invalid_parameter Valor informado no parâmetro é inválido ou não corresponde ao formato esperado. 400
40003 parameter_unknow Parâmetro desconhecido ou não esperado. 400
40004 rate_limit Limite de uso da API excedido. 400
40005 idempotency_key_in_use Chave de idempotência já em uso. 409
40006 unabled_capture Captura já realizada, expirada ou transação com status inválido. 400
40007 unabled_refund Reembolso já realizado, ou valor solicitado acima do permitido. 400
40008 refund_temporarily_unavailable Reembolso temporariamente indisponível - Tente novamente mais tarde. 400

Lista de erros associados a divisão do pagamento

Os códigos de erro apresentados na tabela abaixo podem ocorrer durante a interação com o endpoint Criar pedido ou Pagar pedido quando a opção de divisão do pagamento é utilizada. Esses códigos são acompanhados por pequenas descrições. Consulte a tabela abaixo para obter mais informações sobre cada código de erro e o respectivo parâmetro associado ao erro.

CódigoOrigem do erroDescriçãoHTTP Status
parameter_required_missingsplits.receiversPayment split receivers must be informed.`400
parameter_required_emptysplits.receiversPayment split receivers must be informed.400
parameter_required_missingsplits.receivers.account.idReceiver account id must be informed.400
parameter_required_emptysplits.receivers.account.idReceiver account id must be informed.400
invalid_idreceivers.account.idThe receiver {id da conta PagBank} was not found.404
parameter_required_missingsplits.receivers.amount.valueReceiver amount must be informed.400
invalid_amountsplits.receivers.amount.valueReceiver amount must be positive and non-zero.400
invalid_min_receivers--At least two receivers must be informed in a split payment.400
invalid_max_receivers--Transaction must have 2 receivers. If your transaction has more than 2 receivers, please send different transactions for each receiver.400
invalid_receivers_list--Primary seller must be informed in the receivers list and must be the owner of the token.400
invalid_receivers_list--Each split receiver must be informed only once.400
seller_account_required--One or more split receivers cannot receive payments.400
account_inactive--One or more receivers cannot receive payments.400
forbidden--One or more receivers are not allowed to split a payment. If you are interested in our split payment product, please contact us at https://dev.pagseguro.uol.com.br/reference/request-approval.403
parameter_required_missingsplits.methodPayment split method must be informed.400
parameter_required_emptysplits.methodPayment split method must be FIXED or PERCENTAGE.400
invalid_parametersplits.methodPayment split method must be FIXED or PERCENTAGE.400
invalid_parametersplits.receivers.reasonThe reason for a receiver to participate in a split payment must be a maximum of 255 characters.400
amount_too_large--The sum of the amounts of each receiver must equal the total amount of the transaction.400
amount_too_smal--The sum of the amounts of each receiver must equal the total amount of the transaction.400
amount_too_large--The sum of the percentages of each receiver must equal 100%.400
amount_too_small--The sum of the percentages of each receiver must equal 100%.400
forbidden--This user is not authorized to perform this query.403
invalid_id--Sorry, the split data for this payment could not be found.404
parameter_required_missingsplits.sourceSource must be informed.400
parameter_required_emptysplits.sourceCurrently, it is only possible to split a payment via API Charge or API Order.400
invalid_parametersplits.sourceCurrently, it is only possible to split a payment via API Charge or API Order.400
invalid_parametersplits.receivers.configurations.liableThe liable receiver cannot be changed when capturing a pre-authorized split payment.400
invalid_parametersplits.receivers.configurations.liableOnly one receiver can be liable for split payments.400
invalid_parametersplits.receivers.configurations.liableLiable must be applied (true) for one receiver. Or none to set primary as default.400
invalid_parametersplits.receivers.configurations.liableThe liable configuration can only be applied for credit card payments.400
invalid_parameterrecurringRecurring payment is not valid for split transactions with liable configuration.400
invalid_parameterpayment_method.authentication_method.type3DS authentication is not valid method for split transactions with liable configuration400

Lista de erros do endpoint consultar juros de uma transação

Os códigos de erro apresentados na tabela abaixo podem ocorrer durante a interação com o endpoint Consultar juros de uma transação. Esses códigos são acompanhados por pequenas descrições. Consulte a tabela abaixo para obter mais informações sobre cada código de erro e o respectivo cenário.

CódigoDescriçãoCenárioHTTP Status
payment_methods_is_requiredParameter payment_methods is a required parameter.Ocorre quando o integrador envia o meio de pagamento utilizado vazio.400
payment_methods_is_invalidParameter payment_methods with invalid value, see documentation.Ocorre quando o integrador envia o meio de pagamento utilizado com um valor inválido.400
max_installments_no_interest_must_not_be_1Parameter max_installments_no_interest should be equal 0 or greater then 1.Ocorre quando o integrador envia a quantidade de parcelas assumidas igual a 1.400
max_installments_no_interest_outside_rangeParameter max_installments_no_interest should be between 0 and 12.Ocorre quando o integrador envia a quantidade de parcelas assumidas maior ou igual a 13 ou menor que 0.400
max_installments_no_interest_is_invalidParameter max_installments_no_interest has an invalid value, see documentation.Ocorre quando o integrador envia a quantidade de parcelas assumidas com um valor inválido.400
max_installments_outside_rangeParameter max_installments should be between 1 and 12.Ocorre quando o integrador envia a quantidade máxima de parcelas maior ou igual a 13 ou menor que 1.400
max_installments_is_invalidParameter max_installments with invalid value, see documentation.Ocorre quando o integrador envia a quantidade máxima de parcelas com um valor inválido.400
credit_card_bin_invalid_lengthParameter credit_card_bin should have 6 or 8 digits.Ocorre quando o integrador envia o BIN do cartão com valor diferente de 6 ou 8 dígitos.400
credit_card_bin_is_invalidParameter credit_card_bin should be as disposed on the credit card, see documentation.Ocorre quando o integrador envia o BIN do cartão com um valor inválido.400
value_is_requiredParameter value is a required parameter.Ocorre quando o integrador não envia o valor original da transação.400
value_is_invalidParameter value has an invalid value, see documentation.Ocorre quando o integrador envia o valor original da transação com um valor inválido ou acima dos limites suportados.400
credit_card_bin_data_not_foundcredit_card_bin data not found.Ocorre quando o integrador envia o BIN do cartão com um valor inválido.400
fees_not_configuredUser does not have configured fees for these parameters, contact your account manager.Ocorre quando a aplicação não encontra nenhum plano de parcelamento associado ao cliente consultado.400
internal_server_errorInternal server error.Ocorre quando a aplicação identifica um erro interno.500

Lista de erros do endpoint validar e armazenar cartão

Os códigos de erro apresentados na tabela abaixo podem ocorrer durante a interação com o endpoint Validar e armazenar um cartão no PagBank. Esses códigos são acompanhados por pequenas descrições. Consulte a tabela abaixo para obter mais informações sobre cada código de erro e o respectivo cenário.

CódigoDescriçãoCenárioHTTP Status
card_cannot_be_storedCard cannot be stored.Ocorre quando a bandeira do cartão retorna que o cartão não é válido ou não pode realizar transações.400
card_brand_not_supportedCard brand is not supported.Ocorre quando o integrador envia um cartão de uma bandeira não suportada pela API.400
payment_method_not_supportedPayment method is not supported.Ocorre quando o integrador envia um cartão de um meio de pagamento não suportado.400
number_is_requiredParameter ‘number’ is a required parameter.Ocorre quando o integrador não envia o número do cartão ou envia o campo vazio.400
number_is_invalidParameter ‘number’ has an invalid value, see documentation.Ocorre quando o integrador envia a numeração do cartão com um valor inválido.400
number_invalid_lengthParameter 'number' should have between 14 and 19 digits.Ocorre quando o integrador envia a numeração do cartão com valor fora do intervalo entre 14 e 19 dígitos.400
exp_month_is_requiredParameter ‘exp_year’ is a required parameter.Ocorre quando o integrador não envia o ano de expiração do cartão ou envia o campo vazio.400
exp_year_is_invalidParameter ‘exp_year’ has an invalid value, see documentation.Ocorre quando o integrador envia o ano de expiração do cartão com um valor inválido.400
exp_year_invalid_lengthParameter 'exp_year' should have 4 digits.Ocorre quando o integrador envia o ano de expiração do cartão com valor diferente de 4 dígitos.400
security_code_is_requiredParameter 'security_code' is a required parameter.Ocorre quando o integrador não envia o código de segurança do cartão ou envia o campo vazio.400
security_code_is_invalidParameter ‘security_code’ has an invalid value, see documentation.Ocorre quando o integrador envia o código de segurança do cartão com um valor inválido.400
security_code_invalid_lengthParameter 'security_code' should have 3 or 4 digits.Ocorre quando o integrador envia o código de segurança do cartão com valor diferente de 3 ou 4 dígitos.400
internal_server_errorInternal server error.Ocorre quando a aplicação identifica um erro interno não mapeado.500