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.
{
"code": "PIX-0030",
"title": "Idempotency Key Required",
"message": "The X-Idempotency header is required for this operation and must be within the accepted length."
}
{
"type": "https://errors.lerian.studio/v1/PIX-0240",
"title": "Not Found",
"status": 404,
"detail": "No collection found for the given identifiers.",
"code": "PIX-0240"
}
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.
application/problem+json envelope follows RFC 9457:
type– A URI that identifies the error in the Lerian error catalog. Built ashttps://errors.lerian.studio/v1/<code>.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. Usecodeto branch programmatically.code– The samePIX-NNNNidentifier that theapplication/jsonenvelope carries.errors– Optional list of per-field validation details, each with amessageand alocation.instance– Optional URI reference that identifies this specific occurrence.
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 X-Idempotency header is required for this operation and must be within the accepted length. |
| PIX-0031 | Idempotency Key Conflict | 412 | The X-Idempotency header 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-0035 | Idempotent Request In Progress | 409 | An earlier request for this operation is still being processed by the provider. Nothing was executed; retry shortly. |
| 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-0182.
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 X-Idempotency header is required for this operation. |
| PIX-0112 | Idempotency Key Conflict | 412 | The X-Idempotency header 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 | Regulatory Outcome Pending | 409 | The provider accepted the operation but BACEN’s outcome is not yet resolved; keep the operationId and do not retry blindly. |
| PIX-0119 | Entry Mutations Temporarily Blocked | 503 | internal error |
| 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-0125 | Key Absent At BACEN | 404 | BACEN confirmed the key has no entry in the directory. |
| 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-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-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 recorded the given file id. |
| 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. |
| PIX-0175 | CID Events Feed Stalled | 409 | The CID events feed cannot advance past its cursor; reconcile the scope from a CID set file. |
| PIX-0176 | Account Type Not Allowed | 422 | The account type cannot be bound to a Pix key: a salary account (SLRY) is refused on key registration, on claim creation and when an update moves a key onto one. |
| PIX-0177 | Key Owned By Different Person | 409 | The key is registered to a different person. An OWNERSHIP claim is the usual next step. |
| PIX-0178 | Key In Custody Of Different Participant | 409 | The key is registered to the same owner at a different participant. A PORTABILITY claim is the usual next step. |
| PIX-0179 | Owner Or Account Restricted | 422 | The directory refuses this owner or account. Do not retry. |
| PIX-0182 | Claim Refused By Provider | 422 | The provider refused the claim operation. The claim was not changed. |
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 request conflicts with the provider’s current state or with a request still in flight. |
| PIX-0227 | Provider Rejected BR Code | 422 | The provider rejected the BR Code registration. |
| 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-0244 | Create Request In Progress | 409 | The creation for this key is already being processed; retry shortly. |
| PIX-0245 | Create Request Terminated | 422 | The creation for this key can no longer be completed; use a new tx_id or contact support. |
| 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-0455 | Destination Account Holder Mismatch | 422 | Destination account is not held by the declared payee document. |
| 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-0503 | Original Transfer Not Settled | 409 | Original transfer has not settled yet. Retry once it completes. |
| 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-0656 | Surplus Already Returned | 409 | The surplus of this block was already returned; a new settle requires operator reconciliation. |
| 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. |