Payments error list

Error format The Payments API answers a failed request with one of three bodies. Which body you get depends on where the service catches the failure, not on which endpoint you called. A failure that the request pipeline catches before the API layer sees it answers a flat JSON body on application/json. The pipeline authenticates the caller (PBP-0003 at 401) and authorizes the action (PBP-0004 at 403). It also opens the tenant’s storage (PBP-0008 at 503) and runs the idempotency check. Everything the API layer catches answers an RFC 9457 problem document on the application/problem+json media type. The service-wide rate limiter answers 429 with the plain text Too Many Requests and no error code.

{
  "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."
}

Field definitions

type – A URI that identifies the error in the Lerian error catalog. Built as https://errors.lerian.studio/v1/<code>.
title – The HTTP status text, for example Unprocessable Entity.
status – The HTTP status code.
detail – Text about this occurrence of the condition. The wording comes from the branch that raised it.
code – A stable identifier for the condition. Branch on this value.
errors – Optional list of per-field validation details, each with a message, a location, and the value found there.

At status 500, 502 and 503 the detail member carries a fixed text instead of a description of your request, so read code to identify the condition. The flat body carries code, title, message, and an optional details object. It never carries type, status or detail. Five codes reach you as a flat body when the idempotency check raises them: PBP-0002, PBP-0007, PBP-0008, PBP-0012 and PBP-0013. The pipeline also answers this way for a failure that no handler caught. So read the media type rather than the code to tell the two bodies apart.

Platform errors

These codes are not specific to one rail. The transport layer, the request pipeline and the handlers raise them.

`code`	Description	Status
PBP-0001	Malformed request, or a field that fails validation	400
PBP-0002	An unexpected condition inside the service	500
PBP-0003	The service could not establish who the caller is	401
PBP-0004	The caller may not perform this action	403
PBP-0005	The resource named in the request does not exist	404
PBP-0006	A rule declines a well formed request, including a capability this API version does not carry	422
PBP-0007	The request conflicts with the resource state, or with a request still in flight	409
PBP-0008	A dependency this operation needs did not answer	503
PBP-0010	The request body goes past the size limit	413
PBP-0012	The operation needs an idempotency key, and the request carries none or one that is not a valid UUID	400
PBP-0013	The idempotency key belongs to an earlier request that differs from this one	422
PBP-0017	The provider account for this tenant is not fully set up	422
PBP-0019	The path exists, and it does not accept this HTTP method	405
PBP-0020	The request body did not arrive in time	408
PBP-0022	The operation does not accept the content type you sent	415
PBP-0023	A client-side failure that carries no code of its own	400
PBP-0025	The `X-Organization-Id` header is absent or not a valid UUID	400
PBP-0026	The `ledgerId` member is absent or not a valid UUID	400

Provider errors

These codes carry the payment provider’s answer. What is safe to resend depends on the operation, so read the operation’s error descriptions in the API reference before you resend.

`code`	Description	Status
PBP-0014	The payment provider read the instruction and rejected it	422
PBP-0015	The payment provider is unavailable	503
PBP-0016	The provider answered with something this service cannot use	502
PBP-0113	The provider answered the pre-payment consult in a shape this service cannot use	502
PBP-0114	The source of the bill is temporarily unavailable to the bill consult	503
PBP-0211	The payment provider did not receive the payment instruction, and nothing was paid	503

Boleto errors

These codes answer the boleto rail: issuance, installments, cancellation and PDF retrieval.

`code`	Description	Status
PBP-0103	The boleto sits in a state that cancellation does not accept	422
PBP-0105	The boleto PDF is not ready yet at the provider	503
PBP-0106	Boleto issuance cannot check the funding account on this deployment	422
PBP-0107	The provider has no register for the boleto this cancellation names	422
PBP-0108	The nosso número is already in use on the provider account	422
PBP-0109	The installment boleto operations refuse every request	501

Payment errors

These codes answer the bill payment rail: bankslip, utilities, DARF and the bill consult.

`code`	Description	Status
PBP-0100	The digitable line fails its FEBRABAN checksum	422
PBP-0101	The digitable line lacks the digit count its payment type requires	422
PBP-0110	The source has no bank slip under this digitable line	404
PBP-0111	The source refused the line for a reason of its own	422
PBP-0112	The caller went past the bill consult rate limit	429
PBP-0200	The DARF fields fail validation	400
PBP-0202	Payment initiation cannot check the funding account on this deployment	422
PBP-0203	The payment cancellation operation refuses every request	501
PBP-0204	The funding account’s owner record is absent or incomplete, so the payer cannot be established	400
PBP-0205	The funding account’s owner record is inconsistent, so the payer cannot be established	422
PBP-0206	The records that identify the funding account’s owner could not be reached	503
PBP-0207	The funding account owner’s name is longer than a DARF can carry	422
PBP-0208	The funding account owner’s tax document is not all digits	422
PBP-0210	The provider’s pre-payment consult says the slip cannot be paid	422

Ledger errors

These codes carry the ledger’s side of a payment. What is safe to resend depends on the operation, so read the operation’s error descriptions in the API reference before you resend.

`code`	Description	Status
PBP-0300	The funding account lacks the available balance the write needs	422
PBP-0301	The ledger did not complete its step, or the service could not record the payment and did not send it to the provider	503
PBP-0302	The write would take the funding account past its overdraft limit	422

Webhook configuration errors

These codes answer a request that configures where this API pushes event notifications.

`code`	Description	Status
PBP-0400	The callback URL is invalid, or this deployment blocks it	400
PBP-0401	The signing secret is shorter than the minimum length this API accepts	400
PBP-0402	The event list is absent, or it names an event type this API does not publish	400

Inbound provider webhook errors

These four codes answer the payment provider that posts settlement events to the webhook endpoint. They tell that caller which repair its delivery needs.

`code`	Description	Status
PBP-0500	The delivery signature did not authenticate	401
PBP-0501	The delivery body is absent, does not parse, or breaks the envelope schema	400
PBP-0502	The delivery body goes past the endpoint limit	413
PBP-0503	A required envelope member arrives present and blank	400

Boletos API

Payments API

Dashboards API

Admin API

Webhooks API

Error handling

Payments error list

Platform errors

Provider errors

Boleto errors

Payment errors

Ledger errors

Webhook configuration errors

Inbound provider webhook errors

​Platform errors

​Provider errors

​Boleto errors

​Payment errors

​Ledger errors

​Webhook configuration errors

​Inbound provider webhook errors

Platform errors

Provider errors

Boleto errors

Payment errors

Ledger errors

Webhook configuration errors

Inbound provider webhook errors