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.
`card_cannot_be_stored`		Card 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.
`card_brand_not_supported`		Card brand is not supported.	Ocorre quando o integrador envia um cartão de uma bandeira não suportada pela API.
`payment_method_not_supported`		Payment method is not supported.	Ocorre quando o integrador envia um cartão de um meio de pagamento não suportado.
`number_is_required`		Parameter ‘number’ is a required parameter.	Ocorre quando o integrador não envia o número do cartão ou envia o campo vazio.
`number_is_invalid`		Parameter ‘number’ has an invalid value, see documentation.	Ocorre quando o integrador envia a numeração do cartão com um valor inválido.
`number_invalid_length`		Parameter '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.
`exp_month_is_required`		Parameter ‘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.
`exp_year_is_invalid`		Parameter ‘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.
`security_code_is_required`		Parameter '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.
`security_code_is_invalid`		Parameter '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.
`security_code_invalid_length`		Parameter ‘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.
`internal_server_error`		Parameter '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.