Indirect Pix BTG error list

Error format

{
   "code": "<error_code>",
   "title": "<error_title>",
   "message": "<error_message>"
}

Field definitions

code – A stable, unique identifier for the error. 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.

This structure ensures you always get actionable feedback when something doesn’t go as expected.

Indirect Pix BTG errors

The following errors can occur when interacting with the Indirect Pix BTG endpoints. Each error follows our standard structure, making it easier to debug and respond to issues programmatically. Refer to the tables below for a list of possible error codes, what they mean, and how to resolve them.

400

Code	Title	Message
PIX-0001	Missing Headers in Request	Your request is missing one or more required header params. Please refer to the documentation to ensure all necessary header params are included in your request.
PIX-0002	Invalid Header Value	One or more header values are invalid. Please refer to the documentation to verify the expected format and allowed values for each header.
PIX-0003	Missing Fields in Request	Your request is missing one or more required fields. Please refer to the documentation to ensure all necessary fields are included in your request.
PIX-0004	Invalid Field Values in Request	Your request contains one or more fields with invalid values. Please refer to the documentation to verify that all fields have the correct values.
PIX-0005	Invalid Field Type in Request	Your request contains one or more fields with an invalid data type. Please refer to the documentation to verify that all fields have the correct type.
PIX-0006	Unexpected Fields in Request	The request body contains more fields than expected. Please send only the allowed fields as per the documentation.
PIX-0007	Missing Path Parameters in Request	Your request is missing one or more required path parameters. Please refer to the documentation to ensure all necessary path parameters are included in your request.
PIX-0008	Invalid Path Parameter in Request	One or more path parameters are invalid. Please refer to the documentation to verify the expected format and allowed values for each path parameter.
PIX-0009	Missing Query Params in Request	Your request is missing one or more required query params. Please refer to the documentation to ensure all necessary query params are included in your request.
PIX-0010	Invalid Query Param in Request	One or more query params are invalid. Please refer to the documentation to verify the expected format and allowed values for each query param.
PIX-0011	Invalid Timestamp Format	The timestamp format is invalid. Please refer to the documentation to verify the expected format.
PIX-0012	Invalid Metadata	The metadata is invalid. Please refer to the documentation to verify the expected format.
PIX-0013	Limit Exceeded	The request exceeded the allowed limit.
PIX-0101	EVP Key Cannot Be Provided	EVP keys cannot be provided manually, they are automatically generated.
PIX-0102	Invalid Key Format	Invalid format for the specified keyType.
PIX-0105	CPF Mismatch	CPF does not match holder document in CRM.
PIX-0106	CNPJ Mismatch	CNPJ does not match holder document in CRM.
PIX-0107	Pix Key Limit Exceeded for Holder	The key limit has been exceeded for the holder.
PIX-0108	Pix Key Limit Exceeded for Type	The key type limit has been exceeded.
PIX-0109	Invalid Opening Date	The opening date in CRM is invalid. Please provide a valid date in the ‘yyyy-mm-dd’ format.
PIX-0116	Empty Keys Array	The keys array must not be empty.
PIX-0117	Keys Array Exceeded Limit	The keys array must not exceed 200 items.
PIX-0118	Key Claim Type Not Allowed	Only PHONE keys are allowed for ownership claims.
PIX-0120	Key Does Not Exist	The Pix key does not exist in DICT.
PIX-0121	Pix Key Locked By Claim	The Pix key is currently locked by another claim process.
PIX-0122	EVP Key Cannot Be Claimed	EVP keys cannot be claimed.
PIX-0124	Cannot Claim Key	It is not possible to claim this key.
PIX-0151	Invalid CID Format	The CID must be a 64-character lowercase hexadecimal string.
PIX-0201	Report Details Too Long	The report details exceed the maximum allowed length of 2000 characters.
PIX-0202	Invalid Email Format	The email format is invalid.
PIX-0203	Invalid Phone Format	The phone format is invalid.
PIX-0205	Invalid Transaction ID Format	The transaction ID format must match a E2E ID format.
PIX-0208	Infraction Fraud Type Required	The fraud type is required when analysis result is AGREED.
PIX-0209	Infraction Analysis Details Required	The analysis details are required when fraud type is OTHER.
PIX-0210	Infraction Analysis Details Too Long	The analysis details exceed the maximum allowed length of 2000 characters.
PIX-0212	Transaction Too Old	The transaction occurred more than 80 days ago and cannot be reported.
PIX-0215	Invalid Transaction Type	The transaction is not a refund transaction. Cancellation of refund infractions can only be used for refund transactions (pacs.004).
PIX-0218	Cancellation Reason Too Long	The cancellation reason exceeds the maximum allowed length of 500 characters.
PIX-0219	Invalid ID Format	The ID must be a valid UUID format.
PIX-0220	Invalid Date Range Order	The modified_before timestamp must be after modified_after timestamp.
PIX-0221	Refund Transaction Too Old	The refund transaction occurred more than 30 days ago and cannot be reported for cancellation.
PIX-0222	Invalid Situation Type	Refund cancellation infraction reports must use situationType OTHER.
PIX-0230	Invalid Refund Amount Format	The refund amount must be in decimal format with exactly 2 decimal places (e.g., 100.50).
PIX-0231	Refund Details Too Long	The refund details exceed the maximum allowed length of 2000 characters.
PIX-0232	Refund Amount Exceeds Transaction	The refund amount cannot exceed the original transaction amount.
PIX-0233	Missing Refund Details	The refundDetails field is required when refundReason is OPERATIONAL_FLAW.
PIX-0235	Missing Refund Transaction ID	The refund transaction ID is required when the refund is accepted (TOTALLY_ACCEPTED or PARTIALLY_ACCEPTED).
PIX-0237	Missing Rejection Reason	The refundRejectionReason is required when analysisResult is REJECTED.
PIX-0238	Missing Analysis Details	The analysisDetails field is required when analysisResult is REJECTED and refundRejectionReason is INVALID_REQUEST.
PIX-0240	Missing Infraction Report	A refund request with reason FRAUD requires a prior infraction report that has been closed with AGREED result.
PIX-0241	Infraction Report Expired	The infraction report was closed more than 72 hours ago. Refund requests must be created within 72 hours of infraction report closure.
PIX-0245	Date Range Exceeds 90 Days	The date range between modifiedAfter and modifiedBefore cannot exceed 90 days.
PIX-0260	Invalid Tax ID Format	The taxIdNumber must be a valid CPF (11 digits) or CNPJ (14 digits) format.
PIX-0261	Invalid Key Format	The key must be between 8 and 32 characters.
PIX-0280	Invalid Key Value	The key value is invalid or exceeds the maximum length of 77 characters.
PIX-0300	Invalid EMV Format	The EMV payload does not follow the valid EMV QCO format specification.
PIX-0301	Corrupted QR Code	The QR Code data is corrupted and cannot be decoded.
PIX-0302	Unsupported QR Code Version	The QR Code version or format is not supported.
PIX-0303	Invalid Payment Date	The payment date exceeds the valid payment period.
PIX-0304	Invalid Amount	The amount must be greater than zero and follow the 0.00 format with two decimals.
PIX-0305	Invalid City	The city must contain only letters and spaces.
PIX-0306	Invalid TxID Format	The txId format is invalid.
PIX-0307	Receiver Key Required	The receiverKey is required.
PIX-0309	Invalid Category Code Format	The categoryCode must be numeric.
PIX-0310	Invalid Merchant Name	The merchant name is required.
PIX-0311	Receiver Key Not Found	The receiverKey was not found.
PIX-0312	Invalid Receiver Key	The receiverKey is invalid.
PIX-0314	EMV Required	The EMV is required.
PIX-0315	Empty EMV Payload	The EMV payload cannot be empty.
PIX-0317	Invalid City Code	The city code is invalid.
PIX-0319	Receiver Key Not Associated	The receiver key is not associated with the account.
PIX-0320	Invalid Merchant Name	The merchant name is required.
PIX-0321	Invalid Merchant City	The merchant city must contain only letters and spaces.
PIX-0322	Invalid Merchant Category Code	The merchant category code must be numeric.
PIX-0324	Invalid Amount Value	The amount is not a valid decimal.
PIX-0327	Invalid Client Request ID	The client request ID must be a valid UUID.
PIX-0328	Invalid Image Type	The image type must be one of: Gif, Jpeg, Png.
PIX-0329	Invalid Pixels Per Module	The pixels per module value is out of bounds.
PIX-0400	Description Too Long	The description field exceeds the maximum allowed length of 140 characters.
PIX-0401	Description Contains HTML	The description contains invalid HTML characters.
PIX-0402	Invalid Amount Format	The amount must be in format 0.00 with exactly 2 decimal places (1-10 digits before decimal).
PIX-0403	Amount Must Be Positive	The amount must be greater than zero.
PIX-0404	Invalid UUID Format	The UUID format is invalid.
PIX-0405	Invalid End-to-End ID Format	The end-to-end ID format is invalid.
PIX-0406	Intra PSP Not Supported	INTRA PSP transfers (same participant) are not supported. The destination bank ISPB cannot be the same as the source PSP.
PIX-0414	Destination Required	Destination is required for MANUAL initiation type.
PIX-0415	Invalid Initiation Type	The initiation type is invalid.
PIX-0416	Key Required	Key is required for KEY initiation type.
PIX-0417	EMV Required	EMV is required for QR_CODE initiation type.
PIX-0418	Invalid Destination	The destination is invalid for MANUAL initiation type.
PIX-0422	Amount Mismatch	The amount does not match the fixed amount from QR code.
PIX-0424	Invalid Amount Value	The amount must be greater than zero.
PIX-0440	Original Transfer Not Cashin	Only cashin transfers can be refunded with cashout refunds.
PIX-0442	Refund Exceeds Original	The refund amount exceeds the original transaction amount.
PIX-0443	Invalid Refund Reason	The refund reason code is invalid.
PIX-0444	Refund Exceeds Net Amount	The partial refund amount exceeds net amount available after fees.
PIX-0450	Destination Bank Required	The destination bank is required.
PIX-0451	Destination Bank Invalid	The destination bank must be 8 digits.
PIX-0452	Destination Branch Required	The destination branch is required.
PIX-0453	Destination Account Required	The destination account is required.
PIX-0454	Destination Account Type Invalid	The destination account type is invalid.
PIX-0455	Destination Document Required	The destination document is required.
PIX-0456	Destination Document Invalid	The destination document is invalid: must be CPF (11 digits) or CNPJ (14 digits).
PIX-0457	Destination Name Required	The destination name is required.
PIX-0458	Destination Person Type Invalid	The destination person type is invalid.
PIX-0459	Destination Person Type Mismatch	Person type does not match document: CPF requires NATURAL_PERSON, CNPJ requires LEGAL_PERSON.
PIX-0700	Collection Not Found	The collection was not found.
PIX-0701	Duplicate Collection TxID	A collection with this txId already exists for the receiver.
PIX-0703	Invalid Collection Type	The collection type is invalid.
PIX-0705	Invalid Collection Amount	The collection amount is invalid.
PIX-0706	Invalid Collection Expiration / Receiver Key Not Owned	The collection expiration is invalid / The receiver key is not associated with the account.
PIX-0707	Invalid Due Date / Invalid Debtor	The due date is invalid / The debtor information is invalid.
PIX-0708	Expiration Too Long / Collection Has No Provider ID	The expiration exceeds the maximum allowed: 30 days (2,592,000 seconds) / The collection has no pactual ID.
PIX-0709	Invalid TxID / Invalid Delete Reason	The txID is invalid or cannot be empty / The delete reason must be DELETED_BY_USER or DELETED_BY_PSP.
PIX-0710	Invalid Receiver Document	The receiver document is invalid or cannot be empty.
PIX-0711	Invalid Receiver Name	The receiver name is invalid or cannot be empty.
PIX-0712	Invalid Receiver Address	The receiver address is required.
PIX-0713	Invalid Debtor Name	The debtor name is invalid or cannot be empty.
PIX-0714	Invalid CPF Format	The CPF format is invalid: must be exactly 11 digits.
PIX-0715	Invalid CNPJ Format	The CNPJ format is invalid: must be exactly 14 digits.
PIX-0716	Invalid Account ID	The account ID is invalid or cannot be empty.
PIX-0717	Invalid Pactual ID	The pactual ID is invalid or cannot be empty.
PIX-0718	Invalid Location ID	The location ID is invalid or cannot be empty.
PIX-0719	Invalid Fine	The fine configuration is incomplete: both type and value must be provided.
PIX-0720	Invalid Interest	The interest configuration is incomplete: both type and value must be provided.
PIX-0721	Invalid Discount	The discount configuration is incomplete: type, value and days before due must be provided.
PIX-0722	Invalid Abatement	The abatement configuration is incomplete: both type and value must be provided.
PIX-0723	Too Many Additional Info	The number of additional info items exceeds the maximum allowed: 50.
PIX-0724	PIX Troco Amount Mismatch	PIX Troco transaction amount must equal original amount.
PIX-0725	Invalid PIX Saque Configuration	PIX Saque cannot have transaction amount, only withdrawal amount.
PIX-0727	Debtor Document Mismatch	The payment debtor document does not match the collection debtor.
PIX-0728	Type Mismatch	The payment type does not match the collection type.
PIX-0729	Collection Amount Mismatch	The payment amount does not match the collection amount.
PIX-1009	Provider Bad Request	Provider rejected the request due to invalid data.
PIX-1081	Invalid Fraud Type	The provider reports that the fraud type is not valid for this operation.

403

Code	Title	Message
PIX-0115	EVP Key Cannot Be Updated	EVP keys cannot be updated.
PIX-0126	Must Be Donor Participant	The claim must be from the donor participant to confirm.
PIX-0135	Donor Cannot Cancel Open Claim	The donor participant cannot cancel a claim in OPEN status.
PIX-0141	Donor Cannot Cancel Confirmed Portability	The donor cannot cancel a confirmed portability claim.
PIX-0145	Unknown Actor	The participant is neither the claimer nor the donor.
PIX-0147	Must Be Claimer Participant	Only the claimer participant can complete a claim.
PIX-0213	Unauthorized to Open Refund Request	A refund request infraction report can only be opened by the payer’s PSP.
PIX-0214	Unauthorized to Open Cancellation Report	A cancellation of refund infraction report can only be opened by the payee’s PSP.
PIX-0216	Unauthorized to Close Refund Request	A refund request infraction report must be closed by the payee’s PSP.
PIX-0217	Unauthorized to Close Cancellation Report	A cancellation of refund infraction report must be closed by the payer’s PSP.
PIX-0431	Account Blocked	The account is blocked and cannot perform transactions.
PIX-0501	CRM Authentication Error	Failed to authenticate with CRM service.
PIX-0601	Midaz Account Blocked	The account is blocked and cannot perform transactions.
PIX-0726	Collection Update Not Allowed	Updates are not allowed for this collection.
PIX-1001	Provider Authentication Error	Failed to authenticate with provider.

404

Code	Title	Message
PIX-0112	Entry Not Found	The entry was not found.
PIX-0113	Claim Not Found	The claim was not found.
PIX-0150	CID File Not Found	The specified CID file was not found or is not ready for download.
PIX-0152	CID Not Found	The specified CID was not found in DICT.
PIX-0200	Infraction Report Not Found	The infraction report was not found.
PIX-0211	Transaction Not Found	The specified transaction was not found.
PIX-0234	Refund Request Not Found	The specified refund request was not found.
PIX-0262	Fraud Marker Not Found	The specified fraud marker was not found.
PIX-0316	EMV Not Found	The EMV QR Code was not found.
PIX-0318	BR Code Not Found	The requested BR Code was not found.
PIX-0407	Transfer Account Mismatch	The transfer does not belong to the specified account.
PIX-0410	Initiation Not Found	The payment initiation was not found.
PIX-0420	Cashout Not Found	The cashout transaction was not found.
PIX-0425	Cashin Not Found	The cashin transaction was not found.
PIX-0426	Transfer Not Found	The transfer was not found.
PIX-0427	Refund Not Found	The refund was not found.
PIX-0430	Account Not Found	The account was not found in ledger.
PIX-0502	Account Not Found in CRM	The account was not found in CRM for the given criteria.
PIX-0503	Holder Not Found in CRM	The holder was not found in CRM.
PIX-1005	Key Not Found	The Pix key was not found.
PIX-1090	Person Statistics Not Found	The provider reports that no statistics were found for the specified tax ID.
PIX-1091	Key Statistics Not Found	The provider reports that no statistics were found for the specified Pix key.

409

Code	Title	Message
PIX-0103	Pix Key Already Exists	The Pix key is already registered.
PIX-0110	Pix Key Belongs to Another Holder	The Pix key is already registered to another holder. Please initiate an ownership claim to acquire this key.
PIX-0111	Pix Key Already Linked to Another Account	The Pix key is already linked to another account of the same holder. Please initiate a portability request to transfer this key.
PIX-0119	Pix Key Already Claimed	You already have a claim in progress for this key.
PIX-0123	Key Already Belongs to Holder	The Pix key is already linked to the requesting holder.
PIX-0160	Claim Already Completed	The claim has already been completed.
PIX-0161	Claim Is Cancelled	The claim has been cancelled and cannot be completed.
PIX-0204	Duplicate Infraction Report	An infraction report already exists for this transaction.
PIX-0242	Duplicate Refund Request	A refund request already exists for this transaction.
PIX-0412	Initiation Already Used	The payment initiation has already been processed.
PIX-0423	Duplicate End-to-End ID	A transaction with this end-to-end ID already exists.
PIX-0428	Duplicate Refund	A refund already exists for this transaction.
PIX-0702	Collection Already Deleted	The collection has already been deleted.
PIX-1006	Key Already Exists	The Pix key already exists.
PIX-1065	Duplicate Refund Request	The provider reports that a refund request already exists for this transaction.
PIX-1080	Duplicate Fraud Marker	The provider reports that a fraud marker already exists for this document and key combination.

422

Code	Title	Message
PIX-0114	Key In Custody Account	The entry queried is in custody of the participant making the query.
PIX-0125	Waiting Resolution Status	The claim must be in WAITING_RESOLUTION status to execute the action.
PIX-0127	Portability Cannot Be Confirmed	Portability claims cannot be confirmed with DEFAULT_OPERATION reason.
PIX-0128	Ownership Cannot Be Confirmed	Ownership claims cannot be confirmed with DEFAULT_OPERATION reason before the resolution period has ended.
PIX-0134	Claim Cannot Be Cancelled	The claim cannot be cancelled in current status.
PIX-0136	Invalid Reason for Claimer	The claimer cannot cancel with the provided reason in this status.
PIX-0137	Invalid Reason for Donor	The donor cannot cancel with the provided reason in this status.
PIX-0142	Resolution Period Not Ended	The resolution period has not ended yet for DEFAULT_OPERATION cancellation.
PIX-0143	Ownership Cancel Period Not Ended	Ownership claims with DEFAULT_OPERATION can only be cancelled after CompletionPeriodEnd + 16 days.
PIX-0144	Donor Cancel Period Expired	The donor can only cancel with FRAUD while CompletionPeriodEnd has not passed.
PIX-0146	Claim Not Confirmed	The claim must be in CONFIRMED status.
PIX-0148	Ownership Completion Period Not Ended	Ownership claims can only be completed after the completion period has ended.
PIX-0149	Claim Not Acknowledgeable	The claim does not meet acknowledgement preconditions (must be OPEN status and caller must be the donor participant).
PIX-0162	Claim Cannot Be Completed	The claim cannot be completed in its current status.
PIX-0163	Completion Period Not Set	The completion period is not set for this claim.
PIX-0164	Completion Period Expired	The completion period has expired for this claim.
PIX-0165	Entry Inactive	The entry is not in active status.
PIX-0206	Infraction Report Cannot Be Cancelled	The infraction report cannot be cancelled in current status.
PIX-0207	Infraction Report Cannot Be Closed	The infraction report cannot be closed in current status.
PIX-0223	Infraction Report Cannot Be Acknowledged	The infraction report cannot be acknowledged in current status.
PIX-0236	Invalid Request Status	The request cannot be closed because it is already in CLOSED or CANCELLED status.
PIX-0239	Cannot Cancel Request	The request cannot be cancelled because it is already in CLOSED or CANCELLED status.
PIX-0243	Refund Request Already Closed	The refund request is already closed.
PIX-0244	Refund Request Already Cancelled	The refund request is already cancelled.
PIX-0263	Cannot Cancel Marker	The fraud marker cannot be cancelled because it is already in CANCELLED status.
PIX-0411	Initiation Expired	The payment initiation has expired.
PIX-0413	Initiation Invalid State	The payment initiation is in an invalid state.
PIX-0421	Insufficient Balance	Insufficient balance to complete the transaction.
PIX-0441	Original Transfer Not Complete	Only completed transactions can be refunded.
PIX-0445	Invalid Transaction Status	Only completed transactions can be refunded.
PIX-0470	Invalid Status Transition	The status transition is invalid.
PIX-0471	Transfer Already Terminal	The transaction is already in a terminal state.
PIX-0472	Cannot Cancel	Cannot cancel transaction in current status.
PIX-0473	Already Terminal	The operation is already in a terminal state.
PIX-0504	Invalid Branch in CRM	The branch returned by CRM is invalid. Expected exactly 4 digits.
PIX-0505	Invalid Account Number in CRM	The account number returned by CRM is invalid. Expected 1-20 digits.
PIX-0506	Invalid Document in CRM	The document (CPF/CNPJ) returned by CRM is invalid.
PIX-0507	Invalid Name in CRM	The name returned by CRM is invalid or exceeds 120 characters.
PIX-0508	Invalid Trade Name in CRM	The trade name returned by CRM is invalid or exceeds 100 characters.
PIX-0509	Invalid Opening Date in CRM	The opening date returned by CRM is invalid. Expected format: yyyy-mm-dd.
PIX-0510	Invalid Account Type in CRM	The account type returned by CRM is invalid. Expected: CACC, SLRY, SVGS, TRAN, or OTHR.
PIX-0600	Midaz Insufficient Funds	Insufficient funds in the source account.
PIX-0704	Invalid Collection Status	The collection status is invalid or does not allow this operation.
PIX-1008	Provider Invalid Response	Provider returned an invalid response.
PIX-1010	Provider Unprocessable	Provider cannot process the request.
PIX-1068	Invalid Request Status	The provider reports that the request is in an invalid state for this operation.
PIX-1069	Cannot Cancel Request	The provider reports that the request cannot be cancelled due to its current state.
PIX-1083	Cannot Cancel Marker	The provider reports that the marker cannot be cancelled due to its current state.

429

Code	Title	Message
PIX-1003	Rate Limit Exceeded	Rate limit exceeded. Please try again later.

500

Code	Title	Message
PIX-0000	Internal Server Error	The server encountered an unexpected error. Please try again later.
PIX-0500	CRM Connection Error	Failed to connect to CRM service.
PIX-0599	CRM Bad Request	CRM returned a bad request error.
PIX-1007	Provider Internal Error	Provider returned an internal error.
PIX-1099	Provider Unmapped Error	Provider returned an unmapped error.

502

Code	Title	Message
PIX-0602	Midaz Connection Error	Failed to connect to Midaz.
PIX-0650	Fee Service Connection Error	Failed to connect to Fee service.
PIX-1000	Provider Connection Error	Failed to connect to provider.

503

Code	Title	Message
PIX-0330	Service Unavailable	The decode service is temporarily unavailable.
PIX-1004	Provider Service Unavailable	Provider service is temporarily unavailable.

504

Code	Title	Message
PIX-1002	Provider Request Timeout	Provider request timed out.

CRM

Fees Engine

Direct Pix

Indirect Pix (BTG)

Indirect Pix BTG error list

Indirect Pix BTG errors

400

403

404

409

422

429

500

502

503

504

CRM

Fees Engine

Direct Pix

Indirect Pix (BTG)

​Indirect Pix BTG errors

​400

​403

​404

​409

​422

​429

​500

​502

​503

​504

Indirect Pix BTG errors

400

403

404

409

422

429

500

502

503

504