Lista de erros do Payments

Formato do erro A API do Payments responde a uma requisição com falha com um dos três corpos possíveis. Qual corpo você recebe depende de onde o serviço captura a falha, não do endpoint que você chamou. Uma falha que o pipeline de requisição captura antes que a camada da API a veja responde com um corpo JSON simples no application/json. O pipeline autentica o chamador (PBP-0003 em 401) e autoriza a ação (PBP-0004 em 403). Ele também abre o armazenamento do tenant (PBP-0008 em 503) e executa a verificação de idempotência. Tudo o que a camada da API captura responde com um documento de problema RFC 9457 no media type application/problem+json. O limitador de taxa de todo o serviço responde 429 com o texto simples Too Many Requests e sem código de erro.

{
  "type": "https://errors.lerian.studio/v1/PBP-0101",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "bankslip digitable line must have 47 digits",
  "code": "PBP-0101"
}

{
  "code": "PBP-0013",
  "title": "Idempotency Key Conflict",
  "message": "The request body does not match the original request for this idempotency key."
}

Definições de campo

type – Um URI que identifica o erro no catálogo de erros da Lerian. Construído como https://errors.lerian.studio/v1/<code>.
title – O texto do status HTTP, por exemplo Unprocessable Entity.
status – O código do status HTTP.
detail – Texto sobre esta ocorrência da condição. O texto vem do trecho de código que a gerou.
code – Um identificador estável para a condição. Baseie o tratamento nesse valor.
errors – Lista opcional de detalhes de validação por campo, cada um com uma message, uma location e o value encontrado ali.

Nos status 500, 502 e 503, o membro detail traz um texto fixo em vez de uma descrição da sua requisição, então leia code para identificar a condição. O corpo simples traz code, title, message e um objeto details opcional. Ele nunca traz type, status ou detail. Cinco códigos chegam até você como corpo simples quando a verificação de idempotência os gera: PBP-0002, PBP-0007, PBP-0008, PBP-0012 e PBP-0013. O pipeline também responde assim para uma falha que nenhum handler capturou. Então leia o media type em vez do código para diferenciar as duas formas de corpo.

Erros de plataforma

Esses códigos não são específicos de um trilho. A camada de transporte, o pipeline de requisição e os handlers os geram.

`code`	Descrição	Status
PBP-0001	Requisição malformada, ou um campo que falha na validação	400
PBP-0002	Uma condição inesperada dentro do serviço	500
PBP-0003	O serviço não conseguiu identificar quem é o chamador	401
PBP-0004	O chamador não pode executar esta ação	403
PBP-0005	O recurso indicado na requisição não existe	404
PBP-0006	Uma regra recusa uma requisição bem formada, incluindo uma funcionalidade que esta versão da API não oferece	422
PBP-0007	A requisição conflita com o estado do recurso, ou com uma requisição ainda em andamento	409
PBP-0008	Uma dependência necessária para esta operação não respondeu	503
PBP-0010	O corpo da requisição ultrapassa o limite de tamanho	413
PBP-0012	A operação exige uma chave de idempotência, e a requisição não traz nenhuma ou traz uma que não é um UUID válido	400
PBP-0013	A chave de idempotência pertence a uma requisição anterior que difere desta	422
PBP-0017	A conta do provedor para este tenant não está totalmente configurada	422
PBP-0019	O caminho existe, e não aceita este método HTTP	405
PBP-0020	O corpo da requisição não chegou a tempo	408
PBP-0022	A operação não aceita o content type enviado	415
PBP-0023	Uma falha do lado do chamador que não traz código próprio	400
PBP-0025	O header `X-Organization-Id` está ausente ou não é um UUID válido	400
PBP-0026	O membro `ledgerId` está ausente ou não é um UUID válido	400

Erros do provedor

Esses códigos trazem a resposta do provedor de pagamento. O que é seguro reenviar depende da operação, então leia as descrições de erro da operação na referência da API antes de reenviar.

`code`	Descrição	Status
PBP-0014	O provedor de pagamento leu a instrução e a rejeitou	422
PBP-0015	O provedor de pagamentos está indisponível	503
PBP-0016	O provedor respondeu com algo que este serviço não consegue usar	502
PBP-0113	O provedor respondeu à consulta de pré-pagamento em um formato que este serviço não consegue usar	502
PBP-0114	A fonte da conta está temporariamente indisponível para a consulta de conta	503
PBP-0211	O provedor de pagamento não recebeu a instrução de pagamento, e nada foi pago	503

Erros de boleto

Esses códigos respondem no trilho de boleto: emissão, parcelas, cancelamento e obtenção do PDF.

`code`	Descrição	Status
PBP-0103	O boleto está em um estado que o cancelamento não aceita	422
PBP-0105	O PDF do boleto ainda não está pronto no provedor	503
PBP-0106	A emissão de boleto não consegue verificar a conta de fundeio neste deployment	422
PBP-0107	O provedor não tem registro do boleto que este cancelamento indica	422
PBP-0108	O nosso número já está em uso na conta do provedor	422
PBP-0109	As operações de boleto parcelado recusam toda requisição	501

Erros de pagamento

Esses códigos respondem no trilho de pagamento de contas: bankslip, utilities, DARF e a consulta de conta.

`code`	Descrição	Status
PBP-0100	A linha digitável falha na verificação de checksum da FEBRABAN	422
PBP-0101	A linha digitável não tem a quantidade de dígitos exigida pelo tipo de pagamento	422
PBP-0110	A fonte não tem nenhum boleto bancário com esta linha digitável	404
PBP-0111	A fonte recusou a linha por um motivo próprio	422
PBP-0112	O chamador ultrapassou o rate limit da consulta de conta	429
PBP-0200	Os campos do DARF falham na validação	400
PBP-0202	A iniciação do pagamento não consegue verificar a conta de fundeio neste deployment	422
PBP-0203	A operação de cancelamento de pagamento recusa todas as requisições	501
PBP-0204	O registro do titular da conta de fundeio está ausente ou incompleto, então o pagador não pode ser identificado	400
PBP-0205	O registro do titular da conta de fundeio é inconsistente, então o pagador não pode ser identificado	422
PBP-0206	Os registros que identificam o titular da conta de fundeio não puderam ser acessados	503
PBP-0207	O nome do titular da conta de fundeio é maior do que um DARF comporta	422
PBP-0208	O documento fiscal do titular da conta de fundeio não tem apenas dígitos	422
PBP-0210	A consulta de pré-pagamento do provedor diz que a conta não pode ser paga	422

Erros do ledger

Esses códigos trazem o lado do ledger em um pagamento. O que é seguro reenviar depende da operação, então leia as descrições de erro da operação na referência da API antes de reenviar.

`code`	Descrição	Status
PBP-0300	A conta de fundeio não tem o saldo disponível que a escrita exige	422
PBP-0301	O ledger não concluiu a etapa dele, ou o serviço não conseguiu registrar o pagamento e não o enviou ao provedor	503
PBP-0302	A escrita levaria a conta de fundeio além do limite de overdraft dela	422

Erros de configuração de webhook

Esses códigos respondem a uma requisição que configura para onde esta API envia as notificações de eventos.

`code`	Descrição	Status
PBP-0400	A URL de callback é inválida, ou este deployment a bloqueia	400
PBP-0401	O segredo de assinatura é mais curto que o comprimento mínimo aceito por esta API	400
PBP-0402	A lista de eventos está ausente, ou indica um tipo de evento que esta API não publica	400

Erros de webhook de entrada do provedor

Esses quatro códigos respondem ao provedor de pagamento que envia eventos de liquidação ao endpoint de webhook. Eles informam a esse chamador qual correção a entrega precisa.

`code`	Descrição	Status
PBP-0500	A assinatura da entrega não foi autenticada	401
PBP-0501	O corpo da entrega está ausente, não é possível interpretá-lo, ou ele quebra o schema do envelope	400
PBP-0502	O corpo da entrega ultrapassa o limite do endpoint	413
PBP-0503	Um membro obrigatório do envelope chega presente e em branco	400

API de Boletos

API de Pagamentos

API de Dashboards

API de Administração

API de Webhooks

Tratamento de erros

Lista de erros do Payments

Erros de plataforma

Erros do provedor

Erros de boleto

Erros de pagamento

Erros do ledger

Erros de configuração de webhook

Erros de webhook de entrada do provedor

​Erros de plataforma

​Erros do provedor

​Erros de boleto

​Erros de pagamento

​Erros do ledger

​Erros de configuração de webhook

​Erros de webhook de entrada do provedor

Erros de plataforma

Erros do provedor

Erros de boleto

Erros de pagamento

Erros do ledger

Erros de configuração de webhook

Erros de webhook de entrada do provedor