> ## 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.
# Pix Lerian error list
> Pix Lerian returns structured error responses. Look up a PIX-NNNN code to find what it means and the text the response carries.
**Error format**
Pix Lerian answers an error in one of two shapes. The media type on the response tells you which shape you received. A response with the `application/json` media type carries the `code`, `title`, and `message` envelope. A response with the `application/problem+json` media type carries an RFC 9457 problem detail. Both shapes carry the `code` field, so you can branch on the `PIX-NNNN` value.
A refusal raised inside a handler uses the `application/problem+json` shape. A refusal raised before the handler runs uses the `application/json` shape. An unmatched path, a disallowed method, a timeout, a disconnect and the idempotency replay check all refuse before the handler runs.
```json application/json theme={null}
{
"code": "PIX-0030",
"title": "Idempotency Key Required",
"message": "The Idempotency-Key header is required for this operation and must be within the accepted length."
}
```
```json application/problem+json theme={null}
{
"type": "https://errors.lerian.studio/v1/PIX-0240",
"title": "Not Found",
"status": 404,
"detail": "No collection found for the given identifiers.",
"code": "PIX-0240"
}
```
**Field definitions**
The `application/json` envelope carries three fields:
* **`code`** – A stable, unique identifier for the error (`PIX-NNNN`). Useful for programmatic handling and support requests.
* **`title`** – A short, human-readable summary of the issue.
* **`message`** – Detailed guidance to help you resolve the error.
The `application/problem+json` envelope follows RFC 9457:
* **`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, `Not Found`).
* **`status`** – The HTTP status code.
* **`detail`** – A human-readable explanation for this occurrence of the problem. Use `code` to branch programmatically.
* **`code`** – The same `PIX-NNNN` identifier that the `application/json` envelope carries.
* **`errors`** – Optional list of per-field validation details, each with a `message` and a `location`.
* **`instance`** – Optional URI reference that identifies this specific occurrence.
The tables below list the codes by domain. The `Status` column shows the HTTP status for the code. The `detail` column shows the text that the `application/problem+json` shape carries. At status 500 and above that shape carries the fixed text `internal error`, and the tables show it on those rows.
`PIX-0010` and `PIX-0000` are generic fall-through codes. On a refusal raised before the handler runs, either one can carry a status other than the one in the table.
## Common errors
***
DICT, collections, and payments share these codes. They run from `PIX-0000` to `PIX-0061`.
| `code` | Description | Status | `detail` |
| -------- | ------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| PIX-0000 | Internal Server Error | 500 | `internal error` |
| PIX-0001 | Missing Headers in Request | 400 | Your request is missing one or more required header params. |
| PIX-0002 | Missing Fields in Request | 400 | Your request is missing one or more required fields. |
| PIX-0003 | Invalid Field Values in Request | 400 | Your request contains one or more fields with an invalid data type. |
| PIX-0004 | Unauthorized | 401 | Invalid or expired authentication credentials. |
| PIX-0005 | Forbidden | 403 | You do not have permission to perform this operation. |
| PIX-0006 | Too Many Requests | 429 | Rate limit exceeded. Please wait before making additional requests. |
| PIX-0008 | Route Not Found | 404 | The requested resource path does not exist. |
| PIX-0009 | Method Not Allowed | 405 | The HTTP method is not allowed for this resource. |
| PIX-0010 | Client Error | 400 | The request could not be processed due to a client-side error. |
| PIX-0011 | Entity Not Found | 404 | No entity was found for the given ID. Please make sure to use the correct ID. |
| PIX-0012 | Entity Conflict | 409 | The entity already exists or conflicts with an existing resource. |
| PIX-0013 | Unprocessable Operation | 422 | The operation could not be processed due to a business rule violation. |
| PIX-0014 | Action Not Permitted | 403 | The action you are attempting is not allowed in the current environment. |
| PIX-0015 | Invalid Path Parameter | 400 | One or more path parameters are invalid. |
| PIX-0016 | Unsupported Media Type | 415 | The request body must be sent with Content-Type: application/json. |
| PIX-0017 | Invalid Headers in Request | 400 | Your request contains one or more headers with an invalid format. |
| PIX-0018 | Tenant Context Missing | 400 | The request could not be associated with a tenant. Ensure tenant resolution ran for this route. |
| PIX-0020 | Invalid Query Parameter | 400 | One or more query parameters are in an incorrect format. |
| PIX-0021 | Invalid Date Format | 400 | The date fields are in the incorrect format. Please use the 'yyyy-mm-dd' format. |
| PIX-0022 | Invalid Date Range | 400 | Both 'start\_date' and 'end\_date' fields are required and must be in the 'yyyy-mm-dd' format. |
| PIX-0023 | Date Range Exceeds Limit | 400 | The range between 'start\_date' and 'end\_date' exceeds the permitted limit. |
| PIX-0024 | Pagination Limit Exceeded | 400 | The pagination limit exceeds the maximum allowed items per page. |
| PIX-0025 | Invalid Sort Order | 400 | The 'sort\_order' field must be 'asc' or 'desc'. |
| PIX-0026 | Metadata Key Length Exceeded | 400 | A metadata key exceeds the maximum allowed length. |
| PIX-0027 | Metadata Value Length Exceeded | 400 | A metadata value exceeds the maximum allowed length. |
| PIX-0028 | Invalid Metadata Nesting | 400 | The metadata object cannot contain nested values. |
| PIX-0030 | Idempotency Key Required | 400 | The Idempotency-Key header is required for this operation and must be within the accepted length. |
| PIX-0031 | Idempotency Key Conflict | 412 | The Idempotency-Key was already used with a different request. |
| PIX-0032 | Idempotency Unavailable | 503 | `internal error` |
| PIX-0033 | Idempotency Effect Unknown | 409 | A previous attempt under this idempotency key already executed at the provider. The operation must be reconciled before it is retried. |
| PIX-0034 | Payload Too Large | 413 | The request body exceeds the maximum size allowed for this operation. |
| PIX-0050 | Invalid Transaction ID Format | 400 | The transaction ID does not match the required format. |
| PIX-0054 | Gateway Timeout | 504 | `internal error` |
| PIX-0055 | Client Disconnected | 499 | The client disconnected before the request completed. |
| PIX-0061 | Invalid Amount Format | 400 | The amount must be in decimal format with 2 decimal places. |
## DICT and Pix key errors
***
These codes come from Pix key entries, key lookup, claims, fraud markers, funds recoveries, and key synchronization. They run from `PIX-0100` to `PIX-0174`.
| `code` | Description | Status | `detail` |
| -------- | -------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------- |
| PIX-0100 | Invalid Input | 422 | Missing or malformed required fields. |
| PIX-0101 | Invalid Key Format | 400 | Key value does not match expected format for the key type. |
| PIX-0102 | Key Already Exists | 409 | Key value is already registered. |
| PIX-0103 | Key Limit Exceeded | 400 | Account has reached the maximum number of keys for this key type. |
| PIX-0104 | Account Ownership Failed | 400 | Account ownership could not be verified via CRM. |
| PIX-0105 | Entry Not Found | 404 | Key entry does not exist. |
| PIX-0106 | Entry Not Active | 422 | Key entry is not in ACTIVE status. |
| PIX-0107 | No Fields to Update | 400 | No updateable fields provided. |
| PIX-0108 | Deletion Reason Required | 400 | Deletion reason was not provided. |
| PIX-0109 | Invalid Filter | 400 | Invalid filter parameter value. |
| PIX-0110 | Funds Recovery Not Found | 404 | No funds recovery exists with the provided ID for this participant. |
| PIX-0111 | Idempotency Key Required | 400 | The Idempotency-Key header is required for this operation. |
| PIX-0112 | Idempotency Key Conflict | 412 | The Idempotency-Key was already used with a different request body. |
| PIX-0113 | Funds Recovery Already Exists | 409 | A funds recovery already exists for this root transaction. |
| PIX-0114 | Invalid Funds Recovery State Transition | 409 | The requested operation is not allowed from the current funds recovery status. |
| PIX-0115 | Person Statistics Not Found | 404 | No statistics projection exists for the provided tax id. |
| PIX-0116 | Account Not Found | 422 | Account or holder not found for the provided key or account. |
| PIX-0117 | Funds Recovery Contestation Deadline Expired | 422 | The regulatory contestation deadline for this transaction has already expired. |
| PIX-0118 | Funds Recovery Outcome Pending | 409 | The provider accepted the operation but BACEN's outcome is not yet resolved; poll the operation before retrying. |
| PIX-0120 | Key Not Found | 404 | Key does not exist in the DICT directory. |
| PIX-0121 | Empty Key List | 400 | At least one key must be provided for the check operation. |
| PIX-0122 | Key List Exceeds Limit | 400 | The number of keys exceeds the maximum allowed (200). |
| PIX-0124 | Key In Custody | 409 | The requested key is already in the custody of the requesting account. |
| PIX-0130 | Fraud Marker Not Found | 404 | The requested fraud marker was not found at the provider. |
| PIX-0131 | Fraud Marker Conflict | 409 | The fraud marker operation conflicts with its current state at the provider. |
| PIX-0132 | Request ID Already Used | 400 | This requestId was already used with different parameters. |
| PIX-0133 | Fraud Marker Forbidden | 403 | The caller is not authorized to perform this fraud marker operation. |
| PIX-0134 | Fraud Marker Rate Limited | 429 | The provider rate-limited this fraud marker operation. |
| PIX-0140 | CRM Unavailable | 502 | `internal error` |
| PIX-0141 | Adapter Failure | 502 | `internal error` |
| PIX-0142 | Missing Required Field | 400 | A required field or header is missing from the claim request. |
| PIX-0143 | Invalid Field Value | 400 | One or more claim fields or headers have an invalid value. |
| PIX-0144 | Request Id Replay Mismatch | 409 | The X-Request-Id was already seen with a different request body. |
| PIX-0145 | Claim Not Found | 404 | No claim was found for the given identifier and account. |
| PIX-0146 | Unsupported Claim Configuration | 422 | The requested claim type and key type combination is not supported. |
| PIX-0147 | Invalid Claim Transition | 422 | The requested claim state transition is not permitted. |
| PIX-0148 | Claim Rate Limit Exceeded | 429 | The rate limit for this claim operation has been exceeded. |
| PIX-0149 | Claim Already Active For Key | 422 | An active claim already exists for this key. |
| PIX-0150 | Daily Budget Exhausted | 429 | Daily request budget is exhausted for createCidSetFile. |
| PIX-0151 | VSync State Not Found | 404 | No VSync state exists for the requested scope. |
| PIX-0152 | Reconciliation Job Not Found | 404 | Reconciliation job does not exist. |
| PIX-0153 | Discrepancy Not Found | 404 | Discrepancy record does not exist. |
| PIX-0154 | Discrepancy Already Resolved | 409 | Discrepancy has already been resolved. |
| PIX-0155 | Job Not Retryable | 409 | Reconciliation job is not in a retryable state. |
| PIX-0156 | Active Job Exists | 409 | An active reconciliation job already exists for this scope. |
| PIX-0157 | Invalid Scope | 400 | Unknown ISPB or key type in the requested scope. |
| PIX-0158 | Verification Budget Exhausted | 429 | Request budget is exhausted for sync verifications. |
| PIX-0159 | Scope Not Escalation Blocked | 409 | The requested scope is not in ESCALATION\_BLOCKED status. |
| PIX-0160 | Reconciliation Log Not Found | 404 | Reconciliation log entry does not exist. |
| PIX-0161 | Webhook Job Not Found | 404 | No reconciliation job found for the given scope. |
| PIX-0162 | Invalid Webhook Payload | 400 | The webhook payload is invalid or contains inconsistent data. |
| PIX-0163 | Claim Blocked By Fraud | 422 | The claim was rejected because the key is marked for fraud. |
| PIX-0164 | Claim Adapter Unavailable | 503 | `internal error` |
| PIX-0165 | Claim Not Acknowledgeable | 422 | The acknowledge preconditions are not met for this claim. |
| PIX-0166 | Same Participant | 422 | The donor and claimer participants must differ. |
| PIX-0167 | Resolution Period Missing | 422 | The resolution period is required for this claim transition. |
| PIX-0168 | Terminal State | 422 | The claim is in a terminal state and cannot be mutated. |
| PIX-0169 | Claim Mutations Temporarily Blocked | 503 | `internal error` |
| PIX-0171 | Key Does Not Exist | 422 | The key is not registered in the directory; there is nothing to claim. |
| PIX-0172 | Invalid Opening Date | 422 | The account opening date returned by CRM could not be parsed. |
| PIX-0173 | Key Already Belongs To Holder | 422 | The key already belongs to the requesting holder. |
| PIX-0174 | Invalid Verify-Sync Scope | 422 | Unknown ISPB or key type in the requested verify-sync scope. |
## Collections and BR Code errors
***
These codes come from BR Codes, immediate collections, and due-date collections. They run from `PIX-0200` to `PIX-0267`.
| `code` | Description | Status | `detail` |
| -------- | -------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| PIX-0200 | Invalid Input | 400 | Missing or malformed required fields. |
| PIX-0201 | Key Not Found | 422 | Pix key does not exist or is not active. |
| PIX-0202 | Merchant Name Too Long | 400 | Merchant name exceeds the 25-character EMV limit. |
| PIX-0203 | Merchant City Too Long | 400 | Merchant city exceeds the 15-character EMV limit. |
| PIX-0204 | EMV Generation Failed | 500 | `internal error` |
| PIX-0205 | BR Code Not Found | 404 | BR Code does not exist for this organization. |
| PIX-0206 | Invalid Filter | 400 | Invalid filter parameter value. |
| PIX-0207 | BR Code Field Too Long To Encode | 422 | keyValue and description together exceed the length the BR Code merchant template can encode. Shorten the description, or use a shorter Pix key. |
| PIX-0220 | Malformed EMV Payload | 400 | EMV payload is malformed or not a valid Pix QR code. |
| PIX-0221 | QR Decode Failed | 400 | QR code could not be parsed. |
| PIX-0222 | Dynamic QR Resolution Failed | 502 | `internal error` |
| PIX-0223 | Adapter Unreachable | 502 | `internal error` |
| PIX-0224 | Provider Rejected Collection | 400 | The provider rejected the collection request. |
| PIX-0225 | Provider Resource Not Found | 404 | The requested collection resource was not found at the provider. |
| PIX-0226 | Provider State Conflict | 409 | The collection is in a conflicting state at the provider. |
| PIX-0240 | Collection Not Found | 404 | No collection found for the given identifiers. |
| PIX-0241 | Collection In Terminal State | 422 | Collection is in a terminal state (already CANCELLED or COMPLETED) and cannot transition. |
| PIX-0242 | Collection Already Paid | 409 | Collection has already been marked as paid. |
| PIX-0260 | Due Date Required | 400 | The due-date calendar (dueDate/validityAfterDue) is required for a due-date collection. |
| PIX-0261 | Validity After Due Invalid | 400 | validityAfterDue must be zero or a positive number of calendar days. |
| PIX-0262 | Debtor Required | 400 | The debtor block is required for a due-date collection. |
| PIX-0263 | Fine Terms Invalid | 400 | The fine (multa) modality or value is invalid. |
| PIX-0264 | Interest Terms Invalid | 400 | The interest (juros) modality or value is invalid. |
| PIX-0265 | Abatement Terms Invalid | 400 | The abatement (abatimento) modality or value is invalid. |
| PIX-0266 | Discount Terms Invalid | 400 | The discount (desconto) modality, value, or fixed dates are invalid. |
| PIX-0267 | Due Date Invalid | 400 | dueDate must not be earlier than today. |
## Payments and refund errors
***
These codes come from Pix transfers, refunds, and their settlement. They run from `PIX-0300` to `PIX-0706`.
| `code` | Description | Status | `detail` |
| -------- | ------------------------------------ | ------ | ---------------------------------------------------------------------------------------- |
| PIX-0300 | Missing or Malformed Fields | 400 | Missing or malformed required fields for transfer initiation. |
| PIX-0301 | Initiation Type Mismatch | 400 | initiationType does not match provided destination fields. |
| PIX-0302 | Source Account Invalid | 400 | Source account not found or inactive in CRM. |
| PIX-0303 | DICT Key Not Found | 422 | DICT key lookup returned no results. |
| PIX-0304 | QR Code Decode Failed | 422 | QR code could not be decoded. |
| PIX-0320 | Initiation Not Found | 404 | Initiation ID does not exist. |
| PIX-0321 | Initiation Expired | 422 | Initiation has expired. |
| PIX-0322 | Initiation Already Confirmed | 409 | Initiation was already confirmed. |
| PIX-0323 | Midaz Debit Failed | 422 | Midaz debit failed due to insufficient balance. |
| PIX-0324 | Midaz Transaction Failed | 502 | `internal error` |
| PIX-0325 | Provider Call Failed After Debit | 502 | `internal error` |
| PIX-0326 | Initiation Cancelled | 409 | Initiation has been cancelled and cannot be processed. |
| PIX-0327 | Transfer Conflict | 409 | The transfer changed during this request. Retry the operation. |
| PIX-0328 | Ledger Account Blocked | 422 | The ledger account is blocked and cannot be used for the requested operation. |
| PIX-0329 | Ledger Balance Not Found | 422 | No balance record exists for the account and asset. |
| PIX-0340 | Transfer Not Found | 404 | Transfer ID does not exist for this organization. |
| PIX-0341 | Invalid Filter Parameter | 400 | Invalid filter parameter value. |
| PIX-0342 | Date Range Exceeds Limit | 400 | Date range exceeds 90 days. |
| PIX-0400 | Original Transfer Not Found | 404 | Original transfer does not exist. |
| PIX-0401 | Transfer Not Completed | 422 | Original transfer is not in COMPLETED status. |
| PIX-0402 | Refund Amount Exceeds Remaining | 422 | Refund amount exceeds remaining refundable amount. |
| PIX-0403 | Missing or Malformed Fields | 400 | Missing or malformed required fields for refund. |
| PIX-0404 | Provider Call Failed | 502 | `internal error` |
| PIX-0405 | Midaz Transaction Failed | 502 | `internal error` |
| PIX-0406 | Refund Conflict | 409 | The refund changed during this request. Retry the operation. |
| PIX-0420 | Refund Not Found | 404 | Refund ID does not exist for this organization. |
| PIX-0421 | Invalid Filter Parameter | 400 | Invalid filter parameter value. |
| PIX-0422 | Date Range Exceeds Limit | 400 | Date range exceeds 90 days. |
| PIX-0450 | Destination Account Not Found | 422 | Destination account does not exist. |
| PIX-0451 | Destination Account Not Active | 422 | Destination account is not active. |
| PIX-0453 | CRM Unavailable | 502 | `internal error` |
| PIX-0454 | Midaz Unavailable | 502 | `internal error` |
| PIX-0470 | Payment Not Found | 404 | No approved payment for this endToEndId. |
| PIX-0472 | Midaz Credit Failed | 502 | `internal error` |
| PIX-0500 | Original Transfer Not Found | 404 | Original transfer not found for this endToEndId. |
| PIX-0501 | Refund Exceeds Remaining | 422 | Refund exceeds remaining refundable amount. |
| PIX-0502 | Missing or Malformed Fields | 400 | Missing or malformed required fields. |
| PIX-0520 | Refund Not Found | 404 | No approved refund for this endToEndId. |
| PIX-0521 | Already Settled | 409 | Refund was already settled. |
| PIX-0522 | Midaz Credit Failed | 502 | `internal error` |
| PIX-0550 | Entity Not Found | 404 | No PROCESSING entity found for this endToEndId. |
| PIX-0551 | Unexpected State | 409 | Callback received for entity not in PROCESSING state. |
| PIX-0552 | Invalid Status | 400 | Status is not a valid terminal state. |
| PIX-0553 | Midaz Revert Failed | 502 | `internal error` |
| PIX-0554 | Entity Already Terminal | 409 | The entity has already reached a terminal state; there is nothing to unblock. |
| PIX-0555 | Insufficient Processing Age | 409 | The entity has not been in PROCESSING long enough to be unblocked; wait and retry. |
| PIX-0556 | Provider Has No Terminal Outcome Yet | 409 | The provider has not reached a terminal outcome for this entity yet; wait and retry. |
| PIX-0557 | Provider Unreachable | 502 | `internal error` |
| PIX-0650 | Blocking Account Not Configured | 422 | The blocking account is not configured for this participant. |
| PIX-0652 | Ledger Failure | 502 | `internal error` |
| PIX-0653 | Settle In Progress | 409 | The block is settling and cannot be cancelled or restarted; confirm or close it instead. |
| PIX-0654 | Nothing To Settle | 422 | There is nothing left to settle for this block. |
| PIX-0655 | Account Alias Unresolvable | 422 | An account required for this operation has no resolvable alias in the ledger. |
| PIX-0700 | DICT Hub Unavailable | 502 | `internal error` |
| PIX-0701 | COB Hub Unavailable | 502 | `internal error` |
| PIX-0702 | CRM Unavailable | 502 | `internal error` |
| PIX-0703 | Resource Not Found | 404 | The requested SPI resource was not found. |
| PIX-0704 | State Conflict | 409 | The resource is in a conflicting state for the requested operation. |
| PIX-0705 | Upstream Service Unavailable | 502 | `internal error` |
| PIX-0706 | Bad Request | 400 | The request is invalid. |