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. A camada de autenticação e autorização é executada antes de tudo o mais e responde em texto simples, com um motivo isolado e sem código de erro. Uma falha capturada em seguida pelo pipeline de requisição, antes que a camada da API a veja, responde com um corpo JSON simples no application/json. A verificação de idempotência é a regra do pipeline que você encontra com mais frequência. Tudo o que a camada da API captura responde com um documento de problema RFC 9457 no media type application/problem+json.

{
  "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, no formato PBP-NNNN. 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. O membro code guarda o mesmo valor PBP-NNNN nos dois corpos JSON. Baseie o tratamento nesse valor, e trate 401 e 403 pelo status, porque uma recusa da camada de autenticação não traz código. 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. Leia o media type em vez do código para diferenciar as duas formas de corpo, porque o pipeline também responde assim para uma falha que nenhum handler capturou, e essa falha pode trazer qualquer código.

Erros de plataforma

Esses códigos respondem em qualquer endpoint. A camada de transporte e o pipeline de requisição compartilhado os geram, então trate-os em todos os trilhos.

`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 recebeu a requisição e não conseguiu identificar quem é o chamador. Uma recusa da camada de autenticação responde em texto simples e não traz código	401
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-0009	O chamador ultrapassou o limite de taxa de requisições	429
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	400
PBP-0013	A chave de idempotência pertence a uma requisição anterior com um corpo diferente	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 cliente que não traz código próprio	400

Erros do provedor

Três códigos trazem a resposta do provedor de pagamento sobre uma instrução de pagamento. O PBP-0014 significa que o provedor leu a instrução e a recusou, então corrija a causa antes de enviar uma nova requisição. Para PBP-0015 e PBP-0016, o provedor não deu uma resposta utilizável. O PBP-0014 é gerado antes de esta API escrever qualquer coisa, então repetir a requisição com a mesma chave de idempotência é seguro. PBP-0015 e PBP-0016 deixam o resultado desconhecido, então repita essas com uma nova chave de idempotência.

`code`	Descrição	Status
PBP-0014	O provedor de pagamento leu a instrução e a rejeitou	422
PBP-0015	O provedor de pagamento está temporariamente inacessível	503
PBP-0016	O provedor respondeu com algo que este serviço não consegue usar	502

Erros de boleto

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

`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-0102	O plano de parcelamento falha na validação	422
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

Erros de pagamento

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

`code`	Descrição	Status
PBP-0200	Os campos do DARF falham na validação	400
PBP-0201	O pagamento está em um estado que o cancelamento não aceita	422
PBP-0202	A iniciação do pagamento não consegue verificar a conta de fundeio neste deployment	422
PBP-0203	O cancelamento de pagamento não está implementado nesta versão da API	501

Erros do ledger

Três códigos trazem a resposta do ledger a uma escrita, e o que importa é se o ledger chegou a responder. PBP-0300 e PBP-0302 são recusas: a escrita falhou, então corrija a causa e envie uma nova requisição. PBP-0301 indica que o ledger não deu resposta: o pagamento existe, então não envie nada e, em vez disso, consulte o status dele.

`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 deu resposta, então o resultado da escrita permanece desconhecido	503
PBP-0302	O ledger respondeu e recusou a escrita por causa de uma regra de negócio	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