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 juros 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 ou expirada. | 400 |
40007 |
unabled_refund | Reembolso já realizado, ou valor solicitado acima do permitido. | 400 |
Lista de erros do endpoint consultar taxas de uma transação
Os códigos de erro apresentados na tabela abaixo podem ocorrer durante a interação com o endpoint Consultar taxas 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ódigo | Descrição | Cenário | HTTP Status |
|---|---|---|---|
| "payment_methods_is_required" | Parameter payment_methods is a required parameter. | Ocorre quando o integrador envia o meio de pagamento utilizado vazio. | 400 |
| "payment_methods_is_invalid" | Parameter 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_1" | Parameter 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_range" | Parameter 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_invalid" | Parameter 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_range" | Parameter 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_invalid" | Parameter 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_length" | Parameter 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_invalid" | Parameter 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_required" | Parameter value is a required parameter. | Ocorre quando o integrador não envia o valor original da transação. | 400 |
| "value_is_invalid" | Parameter 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_found" | credit_card_bin data not found. | Ocorre quando o integrador envia o BIN do cartão com um valor inválido. | 400 |
| "fees_not_configured" | User 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_error" | Internal 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ódigo | Descrição | Cenário | HTTP Status |
|---|---|---|---|
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. | 400 |
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. | 400 |
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. | 400 |
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. | 400 |
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. | 400 |
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. | 400 |
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. | 400 |
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. | 400 |
exp_year_invalid_length | 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. | 400 |
security_code_is_required | 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. | 400 |
security_code_is_invalid | 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. | 400 |
security_code_invalid_length | 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. | 400 |
internal_server_error | Internal server error. | Ocorre quando a aplicação identifica um erro interno não mapeado. | 500 |