Códigos de Erros

Ao fazer requisições para a API de Pagamentos Recorrentes do PagBank, 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.

Tratamento de erros

Você receberá um HTTP Status 400, 401, 403, 404, 406ou 415 como resposta quando não conseguirmos prosseguir com a operação devido há um parâmetro mal formatado ou valor inesperado. Nesse caso você deve verificar o conteúdo enviado e corrigir o erro para realizar uma nova requisição. No corpo da resposta você encontrará informações sobre o erro enfrentado e sobre o seu tipo, conforme exemplificado no bloco de código abaixo.

{
  "error_messages": [
    {
      "error": "invalid_value",
      "description": "Field has an invalid value. Please check the documentation.",
      "parameter_name": "customer.tax_id"
    }
  ]
}

Lista de erros da API de Pagamento Recorrente

Os códigos de erro apresentados na tabela abaixo podem ocorrer durante a interação com a API de Pagamento Recorrentedo 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	Parâmetro associado ao erro	Descrição	Cenário
`invalid_authorization_header`		Invalid credential. Review AUTHORIZATION header	O header Authorization não adere às especificações da documentação.
`allowlist_access_required`		Allowlist access required. Contact PagBank.	O vendedor não foi homologado pelo PagBank. Contate-nos para mais informações.
`access_denied`		Access denied.	Acesso negado. Contate-nos para mais informações.
`invalid_request_body`		There are some syntax errors in the request payload. Please check the documentation.	Existem erros de sintaxe no corpo da requisição. Os dados estão em um formato inválido.
`field_cannot_be_empty`	Depende da origem do erro.	Field cannot be empty.	O campo referenciado pelo parameter_name não pode ser vazio.
`invalid_length`	Depende da origem do erro.	Field with invalid length. Please check the documentation.	O campo referenciado pelo parameter_name está com um tamanho inválido.
`invalid_list_element_length`	Depende da origem do erro.	List has at least one element with invalid length. Please check the documentation	A lista referenciada pelo parameter_name contém pelo menos um elemento com tamanho inválido.
`invalid_enum`	Depende da origem do erro.	Field with invalid value. Please check the documentation.	O valor informado no campo referenciado pelo parameter_name não é aceito. O campo é do tipo enum e só aceita determinados valores.
`invalid_format`	Depende da origem do erro.	Field has an invalid format. Please check the documentation.	O campo referenciado pelo parameter_name contém um valor que não adere às especificações da documentação.
`invalid_value`	Depende da origem do erro.	Field has an invalid value. Please check the documentation.	O campo referenciado pelo parameter_name contém um valor inválido.
`invalid_list_element_value`	Depende da origem do erro.	List has at least one element with invalid value. Please check the documentation.	A lista referenciada pelo parameter_name contém pelo menos um elemento que não adere às especificações da documentação.
`invalid_shipping_config`	`shipping`	Field shipping has an invalid configuration. Please check the documentation.	O campo shipping possui uma configuração que não adere às especificações da documentação.
`checkout_not_found`		The requested checkout was not found.	O ID de checkout informado no query param é inexistente.
`checkout_expired`		The requested checkout has expired.	O checkout está expirado.
`invalid_discount_value`	`discountAmount`	Informed discount value is invalid. Please check the documentation.	O valor informado de desconto é maior que o valor da compra. O valor da compra é dado por: soma do valor dos itens + valor adicional.
`invalid_cart_total_value`		Total cart value exceeds the maximum value allowed. Please check the documentation.	O valor do carrinho ultrapassa o valor máximo permitido. O valor do carrinho é dado por: soma do valor dos itens + valor do frete + valor adicional - desconto.
`invalid_calculate_shipping_config`	Depende da origem do erro.	It is not possible to calculate the shipping cost with the chosen service type. Please check the documentation.	O shipping.service_type informado é inválido para frete calculado. O valor deve ser PAC, SEDEX ou nulo.
`inconsistent_brand_configurations`	`paymentMethodsConfigs`	There are repeated card brands in the paymentMethodConfigs field.	Existe mais de uma configuração para a mesma bandeira de cartão.
`invalid_payment_method`	`payment_methods_configs[].type`	The payment method is not valid to be configured.	O meio de pagamento informado não tem suporte a configurações customizadas.
`field_brands_is_not_compatible_with_payment_method`	`payment_methods[].type`	The field brands cannot be in request with the given payment method.	O meio de pagamento informado não tem bandeiras.
`invalid_config_option`	`payment_methods_configs[].config_options[]`	The option field or value field are invalid. Please check the documentation.	A configuração de meio de pagamento referenciada pelo parameter_name não adere às especificações da documentação.
`repeated_options`	`payment_methods_configs[].config_options`	There are payment method configuration options repeated.	A configuração de meio de pagamento referenciada pelo parameter_name está repetida.
`inconsistent_checkout_payment_method_configs`	`paymentMethodConfigs`	There are inconsistent payment method configurations.	Existem configurações de meio de pagamento conflitantes.
`invalid_fixed_shipping_configuration`	`shipping.amount`	Field has an invalid configuration for fixed shipping. Please check documentation.	O valor do frete deve ser informado caso o shipping.type contenha o valor FIXED.
`invalid_unmodifiable_address`	`shipping.address`	Address must be complete when it's unmodifiable.	O endereço deve estar completo caso shipping.address_modifiable contenha o valor false.