Payments error list

Look up any Payments error code, the HTTP status it arrives with, and the condition it names, so you can branch on a failed request.

Error format

The Payments API answers every failed request with an RFC 9457 problem document on the application/problem+json media type, whichever endpoint you called and wherever the service catches the failure. A request that goes past the rate limit answers 429 with PBP-0009.

Problem document

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

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.
• instance – The trace identifier of the request, when it has one.

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.

​

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-0009	The service-wide request rate limit is exceeded	429
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, batches, cancellation and PDF retrieval.

code	Description	Status
PBP-0102	The installment series request fails validation	422
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-0116	The issuing account has no registered holder, or the holder’s registration is incomplete, so the final beneficiary cannot be established	400
PBP-0117	The registered holder cannot be used as the boleto’s final beneficiary	422
PBP-0118	The holder’s registration could not be read, or reading it is not configured, so the final beneficiary cannot be established	503
PBP-0119	The payer is the account holder, who is the boleto’s final beneficiary	422
PBP-0120	A hybrid boleto has no usable Pix receiver	422
PBP-0121	The adoption of an installment’s provider title is refused, and nothing is written	422
PBP-0122	A boleto batch holds fewer than 1 or more than 25 items	422
PBP-0123	One or more items of a boleto batch break a rule, and nothing of the batch is issued	422
PBP-0125	Two or more items of a boleto batch carry the same nosso número. It appears only inside itemErrors of PBP-0123	422

​

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