> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 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.
```json Problem document theme={null}
{
"type": "https://errors.lerian.studio/v1/PBP-0101",
"title": "Unprocessable Entity",
"status": 422,
"detail": "bankslip digitable line must have 47 digits",
"code": "PBP-0101"
}
```
```json Flat body theme={null}
{
"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/`.
* **`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 |