Códigos de erro

Ao fazer requisições para a API de Checkout 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 Checkout

Os códigos de erro apresentados na tabela abaixo podem ocorrer durante a interação com a API de Checkout 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	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.