API Reference

Tratamento de erros

A API Pix retorna códigos de status HTTP para indicar sucesso ou falhas das requisições.

  • Códigos 2xx: indicam sucesso.
  • Códigos 4xx: indicam falhas causadas pelas informações enviadas pelo cliente ou pelo estado atual das entidades.
  • Códigos 5xx: indicam problemas no serviço no lado da API Pix.

O campo type identifica o tipo de erro e na API Pix segue o padrão:

https://pix.bcb.gov.br/api/v2/error/<TipoErro>

📘

Observação

O padrão acima não consiste necessariamente em uma URL que apresentará uma página web válida ou um endpoint válido, embora isso possa mudar no futuro. O objetivo primário é apenas identificar o tipo de erro.

Abaixo estão listados os tipos de erro e possíveis violações da API Pix.

Tipos de Erro

Gerais

Esta seção reúne erros que poderiam ser retornados por quaisquer endpoints listados na API Pix.

  • RequisicaoInvalida
    Significado: Requisição inválida.
    HTTP Status Code: 400 Bad Request.

  • AcessoNegado
    Significado: Requisição de participante autenticado que viola alguma regra de autorização.
    HTTP Status Code: 403 Forbidden.

  • NaoEncontrado
    Significado: Entidade não encontrada.
    HTTP Status Code: 404 Not Found.

  • PermanentementeRemovido
    Significado: Indica que a entidade existia, mas foi permanentemente removida.
    HTTP Status Code: 410 Gone.

  • ErroInternoDoServidor
    Significado: Condição inesperada ao processar requisição.
    HTTP Status Code: 500 Internal Server Error.

  • ServicoIndisponivel
    Significado: Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento.
    HTTP Status Code: 503 Service Unavailable.

  • IndisponibilidadePorTempoEsgotado
    Significado: Indica que o serviço demorou além do esperado para retornar.
    HTTP Status Code: 504 Gateway Timeout.

Tag CobPayload

Esta seção reúne erros retornados pelos endpoints organizados sob a tag CobPayload. Esses erros indicam problemas na tentativa de recuperação, via location, do Payload JSON que representa a cobrança.

  • CobPayloadNaoEncontrado
    Significado: A cobrança em questão não foi encontrada para a location requisitada.
    HTTP Status Code: 404 ou 410.
    Endpoints: GET /{pixUrlAccessToken}, GET /cobv/{pixUrlAccessToken}.
    Observação: Se a location exibia uma cobrança, mas não a exibirá mais permanentemente, pode-se aplicar o HTTP status code 410. Se a location não está exibindo nenhuma cobrança, pode-se utilizar o HTTP status code 404.

  • CobPayloadOperacaoInvalida
    Significado: A cobrança existe, mas a requisição é inválida.
    HTTP Status Code: 400.
    Endpoints: GET /cobv/{pixUrlAccessToken}.

Violações:

  • codMun não respeita o schema.
  • codMun não é um código válido segundo a tabela de municípios do IBGE.
  • DPP não respeita o schema.
  • DPP anterior ao momento presente.
  • DPP superior à validade da cobrança em função dos parâmetros calendario.dataDeVencimento e calendario.validadeAposVencimento. Exemplo: dataDeVencimento => 2020-12-25, validadeAposVencimento => 10, DPP => 2021-01-05. Neste exemplo, o parâmetro DPP é inválido.

Tag Cob

Esta seção reúne erros retornados pelos endpoints organizados sob a tag Cob. Esses erros indicam problemas no gerenciamento de uma cobrança para pagamento imediato.

  • CobNaoEncontrado
    Significado: Cobrança não encontrada para o txid informado.
    HTTP Status Code: 404.
    Endpoints: [GET|PATCH] /cob/{txid}.

  • CobOperacaoInvalida
    Significado: A requisição que busca alterar ou criar uma cobrança para pagamento imediato não respeita o schema ou está semanticamente errada.
    HTTP Status Code: 400.
    Endpoints: [POST|PUT|PATCH] /cob/{txid}.

Violações para os endpoints PUT|PATCH /cob/{txid}:

  • O campo cob.calendario.expiracao é igual ou menor que zero.
  • O campo cob.valor.original não respeita o schema.
  • O campo cob.valor.original é zero.
  • O objeto cob.devedor não respeita o schema.
  • O campo cob.chave não respeita o schema.
  • O campo cob.chave corresponde a uma conta que não pertence a este usuário recebedor.
  • O campo solicitacaoPagador não respeita o schema.
  • O objeto infoAdicionais não respeita o schema.
  • O location referenciado por loc.id inexiste.
  • O location referenciado por loc.id já está sendo utilizado por outra cobrança.
  • O location referenciado por cob.loc.id apresenta tipo "cobv" (deveria ser "cob").

Violações específicas para o endpoint PUT /cob/{txid}:

  • A cobrança já existe, não está no status ATIVA, e a presente requisição busca alterá-la.

Violações específicas para o endpoint PATCH /cob/{txid}:

  • A cobrança não está ATIVA, e a presente requisição busca alterá-la.

  • A cobrança está ATIVA, e a presente requisição propõe alterar seu status para REMOVIDA_PELO_USUARIO_RECEBEDOR juntamente com outras alterações.

  • CobConsultaInvalida
    Significado: Os parâmetros de consulta à lista de cobranças para pagamento imediato não respeitam o schema ou não fazem sentido semanticamente.
    HTTP Status Code: 400.
    Endpoints: GET /cob e GET /cob/{txid}.

Violações específicas para o endpoint GET /cob:

  • Algum dos parâmetros informados para a consulta não respeita o schema.
  • O timestamp representado pelo parâmetro fim é anterior ao timestamp representado pelo parâmetro inicio.
  • Ambos os parâmetros cpf e cnpj estão preenchidos.
  • O parâmetro paginacao.paginaAtual é negativo.
  • O parâmetro paginacao.itensPorPagina é negativo.

Violações específicas para o endpoint GET /cob/{txid}:

  • O parâmetro revisao corresponde a uma revisão inexistente para a cobrança apontada pelo parâmetro txid.

Tag CobV

Esta seção reúne erros retornados pelos endpoints organizados sob a tag CobV. Esses erros indicam problemas no gerenciamento de uma cobrança com vencimento.

  • CobVNaoEncontrada
    Significado: Cobrança com vencimento não encontrada para o txid informado.
    HTTP Status Code: 404.
    Endpoints: [GET|PATCH] /cobv/{txid}.

  • CobVOperacaoInvalida
    Significado: A requisição que busca alterar ou criar uma cobrança com vencimento não respeita o schema ou está semanticamente errada.
    HTTP Status Code: 400.
    Endpoints: [PUT|PATCH] /cobv/{txid}.

Violações para os endpoints PUT|PATCH /cobv/{txid}:

  • Este txid está associado a um lote e no referido lote, o status desta cobrança está atribuído como "EM_PROCESSAMENTO" ou "NEGADA".
  • O campo cobv.calendario.dataDeVencimento é anterior à data de criação da cobrança.
  • O campo cobv.calendario.validadeAposVencimento é menor do que zero.
  • O objeto cobv.devedor não respeita o schema.
  • O campo cobv.chave não respeita o schema.
  • O campo cobv.chave corresponde a uma conta que não pertence a este usuário recebedor.
  • O campo solicitacaoPagador não respeita o schema.
  • O objeto infoAdicionais não respeita o schema.
  • O location referenciado por cobv.loc.id inexiste.
  • O location referenciado por cobv.loc.id já está sendo utilizado por outra cobrança.
  • O location referenciado por cobv.loc.id apresenta tipo "cob" (deveria ser "cobv").
  • O campo cobv.valor.original não respeita o schema.
  • O campo cobv.valor.original é zero.

Tag LoteCobV

Esta seção reúne erros referentes a endpoints que tratam do gerenciamento de lotes de cobrança.

  • LoteCobVNaoEncontrado
    Significado: Lote não encontrado para o id informado.
    HTTP Status Code: 404.
    Endpoints: [GET|PATCH] /lotecobv/{id}.

Tag PayloadLocation

Esta seção reúne erros referentes a endpoints que tratam do gerenciamento de locations.

  • PayloadLocationNaoEncontrado
    Significado: Location não encontrada para o id informado.
    HTTP Status Code: 404.
    Endpoints: [GET|PATCH] /loc/{id}, DELETE /loc/{id}/txid.

Tag Pix

Reúne erros em endpoints de gestão de Pix recebidos e solicitação de devoluções.

  • PixNaoEncontrado
    Significado: Pix não encontrada para o e2eid informado.
    HTTP Status Code: 404.
    Endpoints: GET /pix/{e2eid}.

Tag Webhook

Reúne erros dos endpoints que tratam do gerenciamento dos Webhooks da API Pix.

  • WebhookOperacaoInvalida
    Significado: A requisição busca criar um webhook sem respeitar o schema.
    HTTP Status Code: 400.
    Endpoints: PUT /webhook/{chave}.

Violações para o endpoint PUT:

  • O parâmetro {chave} não corresponde a uma chave DICT válida.