Pix Lerian error list

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.

{
  "code": "PIX-0030",
  "title": "Idempotency Key Required",
  "message": "The Idempotency-Key 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"
}

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/<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. 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.

DICT and Pix keys

Collections and BR Codes

Payments and refunds

Error handling

Pix Lerian error list

Common errors

DICT and Pix key errors

Collections and BR Code errors

Payments and refund errors

​Common errors

​DICT and Pix key errors

​Collections and BR Code errors

​Payments and refund errors

Common errors

DICT and Pix key errors

Collections and BR Code errors

Payments and refund errors