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. The authentication and authorization layer runs ahead of everything else and answers plain text with a bare reason and no error code. A failure that the request pipeline catches next, before the API layer sees it, answers a flat JSON body on application/json. The idempotency check is the pipeline rule you meet most often. Everything the API layer catches answers an RFC 9457 problem document on the application/problem+json media type.

{
  "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, in the form PBP-NNNN. 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. The code member holds the same PBP-NNNN value in both JSON bodies. Branch on it, and handle 401 and 403 by status, because a refusal from the authentication layer carries no code. 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. Read the media type rather than the code to tell the two bodies apart, because the pipeline also answers this way for a failure that no handler caught, and that failure can name any code.

Platform errors

These codes answer on any endpoint. The transport layer and the shared request pipeline raise them, so handle them on every rail.

`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 reached the request and could not establish who the caller is. A refusal by the authentication layer answers plain text and carries no code	401
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 caller passed the request rate limit	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	400
PBP-0013	The idempotency key belongs to an earlier request with a different body	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

Provider errors

Three codes carry the payment provider answer on a payment instruction. PBP-0014 means the provider read the instruction and refused it, so correct the cause before you send a new request. For PBP-0015 and PBP-0016 the provider gave no usable answer. PBP-0014 is raised before this API writes anything, so a retry with the same idempotency key is safe. PBP-0015 and PBP-0016 leave the outcome unknown, so retry those with a new idempotency key.

`code`	Description	Status
PBP-0014	The payment provider read the instruction and rejected it	422
PBP-0015	The payment provider is temporarily unreachable	503
PBP-0016	The provider answered with something this service cannot use	502

Boleto errors

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

`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-0102	The installment plan 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

Payment errors

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

`code`	Description	Status
PBP-0200	The DARF fields fail validation	400
PBP-0201	The payment sits in a state that cancellation does not accept	422
PBP-0202	Payment initiation cannot check the funding account on this deployment	422
PBP-0203	Payment cancellation is not built in this API version	501

Ledger errors

Three codes carry the ledger’s answer to a write, and the line that matters is whether the ledger answered at all. PBP-0300 and PBP-0302 are refusals: the write failed, so correct the cause and submit a new request. PBP-0301 says the ledger gave no answer: the payment exists, so submit nothing and poll it instead.

`code`	Description	Status
PBP-0300	The funding account lacks the available balance the write needs	422
PBP-0301	The ledger gave no answer, so the outcome of the write stays unknown	503
PBP-0302	The ledger answered and declined the write for a business rule	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