Pix JD error list

Error format The Pix JD API answers a failed request with application/problem+json. The Detail schema in this API reference describes that body, which follows RFC 9457.

{
  "type": "https://errors.lerian.studio/v1/PIX-0012",
  "title": "PIX Key Not Found",
  "status": 404,
  "detail": "The specified PIX key was not found in the system. Please verify the key value and try again.",
  "code": "PIX-0012"
}

Field definitions

code – Stable, machine-readable domain error code scoped to the emitting service. On this API it has the form PIX-NNNN.
title – A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
detail – A human-readable explanation specific to this occurrence of the problem.
status – The HTTP status code.
type – A URI that identifies the error in the Lerian error catalog, built as https://errors.lerian.studio/v1/<code>.
instance – A URI reference that identifies the specific occurrence of the problem.
errors – An optional list of field-level details. Each entry carries the location that failed, a message, and the value at that location.
upstream – An RFC 9457 extension member. It carries the code and message a proxied third-party provider reported, and it is absent unless the service surfaced one.

How to read these tables Each row starts with the HTTP status the response carries. Then it names the condition. The last column gives the detail text the service sends by default. Where the service composes that text from the failing request, the row says so. At status 500 and above the response carries fixed text, not the raw cause. The detail column shows whether a code sends internal error or a sentence the service wrote for it.

Pix service request and business rules

These codes come from the Pix service itself. They cover request validation, Pix key management, key claims, payment orders, returns, QR codes, indirect participants, and inbound credits.

Request validation and access

`code`	Description	`detail`
`PIX-0001`	400 Field validation error	One or more fields contain validation errors. Please check the fields object for details and correct the invalid values.
`PIX-0002`	400 Bad request	Set by the operation that raised the error.
`PIX-0003`	400 Unexpected fields	Set by the operation that raised the error.
`PIX-0004`	401 Unauthorized	Set by the operation that raised the error.
`PIX-0005`	403 Forbidden	Set by the operation that raised the error.
`PIX-0006`	404 Not found	Set by the operation that raised the error.
`PIX-0007`	409 Conflict	Set by the operation that raised the error.
`PIX-0008`	422 Unprocessable entity	Set by the operation that raised the error.
`PIX-0009`	429 Too many requests	Set by the operation that raised the error.
`PIX-0019`	400 Invalid account type	The account type is invalid for this operation. Please verify the account type and try again.
`PIX-0058`	400 Invalid ID	The provided ID is invalid or malformed. Please verify the ID format and try again.
`PIX-0059`	401 Invalid token	The provided token is invalid or has expired. Please obtain a new token and try again.
`PIX-0060`	400 Location required	Location information is required for this operation. Please provide valid location data.
`PIX-0061`	400 Invalid parameters	One or more request parameters are invalid. Please check the parameter values and try again.
`PIX-0062`	400 Invalid information	The provided information is invalid or incomplete. Please verify all fields and try again.
`PIX-0082`	401 Authentication required	Valid authentication credentials are required to access this resource. Please provide a valid bearer token.
`PIX-0083`	403 Access forbidden	You do not have sufficient permissions to perform this action. Please contact support if you believe this is an error.
`PIX-0084`	400 Request validation error	The request validation failed. Please check all required fields and try again.

Pix keys

`code`	Description	`detail`
`PIX-0010`	422 Invalid Pix key format	The PIX key format is invalid for the specified type. Please verify the format matches the expected pattern and try again.
`PIX-0011`	409 Pix key already exists	A PIX key with this value already exists. Please use a different PIX key.
`PIX-0012`	404 Pix key not found	The specified PIX key was not found in the system. Please verify the key value and try again.
`PIX-0013`	429 Pix key limit exceeded	You have reached the maximum number of PIX keys allowed. Please delete an existing key before creating a new one.
`PIX-0014`	422 Invalid Pix key type	The PIX key type is not valid for this operation. Please use a supported key type.
`PIX-0015`	422 Pix key expired	Set by the operation that raised the error.
`PIX-0016`	422 Pix key pending confirmation	Set by the operation that raised the error.
`PIX-0017`	422 Pix key inactive	Set by the operation that raised the error.
`PIX-0018`	403 Pix key delete not allowed	This PIX key is not registered to the informed account, so it cannot be deleted. Please verify the key and the account.
`PIX-0067`	422 Pix key expired	The PIX key has expired and cannot be used. Please create a new PIX key.
`PIX-0068`	422 Pix key confirmation required	The PIX key requires confirmation before activation. Please check your email or SMS for the confirmation code.
`PIX-0069`	404 Pix key not found	The specified PIX key was not found in the system. Please verify the key value and try again.
`PIX-0070`	422 Invalid Pix key	The PIX key is invalid or has been deactivated. Please use a valid PIX key.
`PIX-0071`	409 Pix key already owned	You already own this PIX key. Each PIX key can only be associated with one account.
`PIX-0072`	422 Pix key limit exceeded	You have reached the maximum number of PIX keys allowed. Please delete an existing key before creating a new one.
`PIX-0073`	422 Invalid Pix key status	The PIX key is not in a valid status for this operation. Please check the key status.
`PIX-0074`	404 Internal Pix key not found	The internal PIX key reference was not found. Please contact support.
`PIX-0086`	422 Document mismatch	The account document does not match the document associated with the PIX key. Only the key owner can claim this key.

Pix key claims

`code`	Description	`detail`
`PIX-0020`	404 Claim not found	The specified claim was not found for this account. Please verify the claim ID and try again.
`PIX-0021`	409 Claim already exists	Set by the operation that raised the error.
`PIX-0022`	422 Pix key claim or scheduled instruction is in a status this action does not allow	The PIX Automatico authorization is not in a valid status for this operation. Please check the authorization status.
`PIX-0023`	422 Claim expired	Set by the operation that raised the error.
`PIX-0024`	403 Claim unauthorized action	Set by the operation that raised the error.
`PIX-0025`	409 Claim already processed	Set by the operation that raised the error.
`PIX-0026`	422 Invalid claim data	Set by the operation that raised the error.
`PIX-0027`	400 Claim names a participant that does not match the key record	Set by the operation that raised the error.

Transactions and payments

`code`	Description	`detail`
`PIX-0028`	404 Transaction not found	Set by the operation that raised the error.
`PIX-0029`	409 Duplicate transaction	A transaction with this identifier already exists. Please use a unique transaction ID.
`PIX-0030`	422 Invalid transaction amount	The transaction amount is invalid. Please provide a valid positive amount.
`PIX-0031`	400 Insufficient balance	Set by the operation that raised the error.
`PIX-0032`	409 Transaction limit exceeded	Set by the operation that raised the error.
`PIX-0033`	422 Invalid recipient data	The recipient data is invalid. Please verify all recipient information.
`PIX-0034`	422 Transaction expired	Set by the operation that raised the error.
`PIX-0035`	422 Transaction cancelled	Set by the operation that raised the error.
`PIX-0036`	422 Invalid transaction status	The transaction status transition is not permitted for the current state.
`PIX-0037`	422 Invalid end-to-end ID	The end-to-end id is invalid for this payment order. Please check the value and try again.
`PIX-0075`	409 Transaction limit exceeded	The transaction amount exceeds your configured limits. Please try a smaller amount or contact support to increase your limits.
`PIX-0076`	409 Insufficient balance	Your account does not have sufficient balance for this transaction. Please add funds to your account and try again.
`PIX-0077`	409 Same bank ID transfer not allowed	Transfers to the same Bank ID are not allowed for this operation. Please use a different destination.
`PIX-0078`	409 Same account transfer not allowed	Transfers to the same account are not allowed. Please use a different destination account.
`PIX-0090`	422 Insufficient funds for block	The payer’s transactional account does not have sufficient funds to reserve the scheduled debit. (SGCTPIX001)
`PIX-0091`	500 Block rejected	`internal error`

Returns and refunds

`code`	Description	`detail`
`PIX-0038`	403 Return not allowed	Set by the operation that raised the error.
`PIX-0039`	422 Invalid return reason	Set by the operation that raised the error.
`PIX-0040`	422 Return amount exceeds original	Set by the operation that raised the error.
`PIX-0041`	403 Return window expired	Set by the operation that raised the error.
`PIX-0042`	404 Original transaction not found	Set by the operation that raised the error.
`PIX-0087`	400 Cannot refund own transaction	You cannot request a refund for your own outgoing transaction. Only the recipient can request a refund.
`PIX-0088`	400 Cannot refund transaction not received	You can only request refunds for transactions you have received.
`PIX-0089`	400 Cannot refund outgoing transaction	Outgoing transactions (CASH_OUT) cannot be refunded. Only received transactions can be refunded.

Participants and accounts

`code`	Description	`detail`
`PIX-0043`	422 Invalid bank ID	Set by the operation that raised the error.
`PIX-0044`	422 Bank ID not participating	Set by the operation that raised the error.
`PIX-0045`	422 Invalid account number	Set by the operation that raised the error.
`PIX-0046`	422 Account blocked	Set by the operation that raised the error.
`PIX-0047`	422 Account closed	Set by the operation that raised the error.

QR codes

`code`	Description	`detail`
`PIX-0048`	422 Invalid QR code	Set by the operation that raised the error.
`PIX-0049`	504 QR code expired	`internal error`
`PIX-0050`	422 QR code already used	Set by the operation that raised the error.

Entities, templates and conciliation

`code`	Description	`detail`
`PIX-0063`	404 Entity not found	The specified entity was not found in the system. Please verify the identifier and try again.
`PIX-0064`	409 Entity already exists	An entity with this identifier already exists. Please use a unique identifier.
`PIX-0065`	409 Conciliation ID already exists	A record with this conciliation ID already exists. Please use a unique conciliation ID.
`PIX-0066`	404 Template not found	The specified template was not found. Please verify the template identifier.
`PIX-0110`	409 Entity already withdrawn	The specified entity has already been withdrawn and can no longer be acted on.

Fraud, compliance and regulation

`code`	Description	`detail`
`PIX-0055`	400 Fraud detected	Set by the operation that raised the error.
`PIX-0056`	403 Compliance violation	Set by the operation that raised the error.
`PIX-0057`	403 Regulatory restriction	Set by the operation that raised the error.

Service and dependency faults

`code`	Description	`detail`
`PIX-0051`	503 Service unavailable	The PIX integration is temporarily unavailable for this tenant. Please try again shortly.
`PIX-0052`	504 Timeout	`internal error`
`PIX-0053`	500 Internal error	`internal error`
`PIX-0054`	502 External service error	`internal error`
`PIX-0079`	502 External service error	`internal error`
`PIX-0080`	500 Core banking error	`internal error`
`PIX-0085`	500 Database connection error	`internal error`
`PIX-0109`	500 Server failure the service could not attribute to a specific condition	`internal error`

Tenant configuration

`code`	Description	`detail`
`PIX-0092`	409 Tenant Pix integration not provisioned	The PIX integration for this tenant has not been provisioned. Please contact support to complete tenant onboarding.
`PIX-0105`	409 Tenant route configuration missing	The PIX routing configuration for this tenant is missing or invalid. Please contact support to complete tenant onboarding.
`PIX-0106`	503 Tenant ledger configuration missing	The Midaz ledger configuration for this tenant is missing or invalid. Please contact support to complete tenant onboarding.
`PIX-0107`	503 Indirect delivery encryption unavailable	The delivery secret encryption key for this tenant is unavailable, so the indirect participant was not saved. No secret was stored. Please contact support to provision the delivery encryption key and try again.
`PIX-0108`	422 Ledger account alias unresolved	Set by the operation that raised the error.

Indirect participants

`code`	Description	`detail`
`PIX-0093`	409 Indirect ISPB conflict	An indirect participant with this ISPB is already registered and active for this tenant. A closed indirect may be re-registered, but an open one is unique per ISPB.
`PIX-0094`	409 Illegal indirect transition	The requested lifecycle change is not permitted for the indirect participant’s current status.
`PIX-0095`	404 Indirect not found	The specified indirect participant was not found for this tenant. Please verify the identifier and try again.
`PIX-0096`	409 Cannot close indirect with balance	The indirect participant cannot be closed while its PIX account holds funds. Settle the available balance and on-hold amount to zero and try again.
`PIX-0097`	409 Indirect not awaiting provisioning	Provisioning retry is only valid for an indirect participant in the PENDING_PROVISIONING state.
`PIX-0098`	422 Invalid indirect participant	The indirect participant request is invalid. Please verify the name, ISPB, delivery endpoint, secret, and messaging mode and try again.
`PIX-0099`	502 Indirect provisioning failed	`internal error`
`PIX-0100`	422 Indirect not active	The specified indirect participant is not active and cannot originate a transaction. Reactivate it and try again.
`PIX-0102`	422 Indirect payer mismatch	The supplied payer ISPB does not match the resolved indirect participant. Verify the indirect identifier and payer data and try again.
`PIX-0103`	409 Credit park not open	The parked inbound credit is no longer PARKED (it was already resolved or rejected, possibly by a concurrent request). No further action was taken.
`PIX-0104`	409 Indirect target not active	The indirect participant targeted by this resolution is not ACTIVE and cannot receive the credit. Reactivate it or choose a different target.
`PIX-0111`	422 Indirects feature disabled	Set by the operation that raised the error.
`PIX-0112`	422 Indirect QR location too long	Set by the operation that raised the error.
`PIX-0113`	422 Indirect QR host not public	Set by the operation that raised the error.
`PIX-0114`	422 Indirect has no own QR certificate	Set by the operation that raised the error.

Inbound credits

`code`	Description	`detail`
`PIX-0115`	404 Cash-in account not found	The receiving account named by this credit was not found at this participant, so no credit was registered.
`PIX-0116`	409 Cash-in destination ambiguous	The receiver document names more than one account at this participant, so the destination for this credit cannot be determined. No credit was registered. Address the credit to a specific account (recebedor.nrAgencia and recebedor.nrConta) or contact this participant to have the duplicate records corrected.
`PIX-0117`	409 Cash-in holder mismatch	The account addressed by this credit belongs to a different holder than the receiver document names, so no credit was registered. Verify recebedor.cpfCnpj against recebedor.nrAgencia and recebedor.nrConta.
`PIX-0118`	409 Cash-in account not creditable	The account addressed by this credit exists at this participant but is not set up to receive credits, so no credit was registered. Contact this participant to have the account record completed.
`PIX-0119`	404 Cash-in receiver not served	The receiving participant named by this credit is not served by this participant, so no credit was registered. Verify recebedor.ispb.
`PIX-0120`	500 Cash-in ledger misprovisioned	`internal error`

Pix rail and key directory

These codes come from the connected Pix infrastructure. The service translates a rail fault into one of these codes before it answers. A caller branches on a PIX-NNNN value, not on the rail’s own vocabulary.

Request validation and authentication

`code`	Description	`detail`
`PIX-1000`	400 Field validation error	One or more fields contain validation errors. Please check the fields object for details and correct the invalid values.
`PIX-1001`	400 Bad request	The server could not understand the request due to malformed syntax. Please check the request format and try again.
`PIX-1002`	400 Unexpected fields in request	The request body contains more fields than expected. Please send only the allowed fields as per the documentation.
`PIX-1003`	401 Unauthorized	Authentication credentials were missing or incorrect. Please provide valid credentials.
`PIX-1004`	403 Forbidden	The server understood the request but refuses to authorize it. Please check your permissions.
`PIX-1005`	404 Not found	The requested resource was not found. Please verify the identifier and try again.
`PIX-1006`	409 Conflict	The request could not be completed due to a conflict with the current state.
`PIX-1007`	422 Unprocessable entity	The request was well-formed but unable to be processed due to semantic errors.
`PIX-1008`	429 Too many requests	Too many requests have been sent. Please wait before making another request.
`PIX-1059`	400 Authentication token missing	Authentication token is missing in the request. Please provide a valid Bearer token in the Authorization header.
`PIX-1060`	400 Invalid authentication token	The authentication token provided is invalid. Please obtain a new token and try again.
`PIX-1061`	400 Authentication token expired	The authentication token has expired. Please obtain a new token using the authentication endpoint.
`PIX-1062`	400 Insufficient permissions	The authenticated participant does not have sufficient permissions to perform this operation.
`PIX-1063`	400 Participant not authorized	The authenticated participant is not authorized to perform this operation on the specified resource.
`PIX-1064`	400 Authentication or authorization rule was violated	The request violates authentication or authorization rules. Please verify your credentials and permissions.

Pix keys

`code`	Description	`detail`
`PIX-1009`	422 Invalid Pix key format	The PIX key format is invalid for the specified type. Please verify the format matches the expected pattern and try again.
`PIX-1010`	409 Pix key already exists	A PIX key with this value already exists. Please use a different PIX key.
`PIX-1011`	404 Pix key not found	The specified PIX key was not found in the system. Please verify the key value and try again.
`PIX-1012`	400 Pix key limit exceeded	You have reached the maximum number of PIX keys allowed. Please delete an existing key before creating a new one.
`PIX-1013`	422 Invalid Pix key type	The PIX key type is invalid. Please use a valid PIX key type.
`PIX-1014`	422 Pix key expired	The PIX key has expired and cannot be used. Please create a new PIX key.
`PIX-1015`	400 Pix key pending confirmation	The PIX key is pending confirmation. Please complete the confirmation process.
`PIX-1016`	400 Pix key inactive	The PIX key is inactive and cannot be used. Please activate the PIX key.
`PIX-1017`	403 Pix key delete not allowed	The PIX key cannot be deleted in its current state. Please check the key status.
`PIX-1018`	422 Invalid account type	The account type is invalid for this operation. Please use a valid account type.

Pix key claims

`code`	Description	`detail`
`PIX-1019`	404 Pix key claim not found	The specified PIX key claim was not found. Please verify the claim identifier.
`PIX-1020`	409 Pix key claim already exists	A PIX key claim with this identifier already exists. Please use a unique identifier.
`PIX-1021`	422 Invalid claim status	The claim is not in a valid status for this operation. Please check the claim status.
`PIX-1022`	422 Pix key claim expired	The PIX key claim has expired and cannot be processed. Please create a new claim.
`PIX-1023`	403 Unauthorized claim action	You are not authorized to perform this action on the claim. Please check your permissions.
`PIX-1024`	409 Claim already processed	The PIX key claim has already been processed and cannot be modified.
`PIX-1025`	422 Invalid claim data	The claim data provided is invalid. Please verify all fields and try again.
`PIX-1026`	400 Claim bank ID mismatch	There is a Bank ID mismatch in the claim request. Please verify the Bank ID values.

Transactions and payments

`code`	Description	`detail`
`PIX-1027`	404 Transaction not found	The specified transaction was not found. Please verify the transaction identifier.
`PIX-1028`	409 Transaction already exists	A transaction with this identifier already exists. Please use a unique transaction ID.
`PIX-1029`	422 Invalid transaction amount	The transaction amount is invalid. Please provide a valid positive amount.
`PIX-1030`	400 Insufficient balance	The account does not have sufficient balance for this transaction. Please add funds and try again.
`PIX-1031`	409 Transaction limit exceeded	The transaction amount exceeds the configured limits. Please try a smaller amount.
`PIX-1032`	422 Invalid recipient data	The recipient data is invalid. Please verify all recipient information.
`PIX-1033`	422 Transaction expired	The transaction has expired and cannot be processed. Please create a new transaction.
`PIX-1034`	422 Transaction cancelled	The transaction has been cancelled and cannot be processed.
`PIX-1035`	422 Payment validation failed	Payment validation failed. Please verify all payment details and try again.
`PIX-1036`	400 Invalid end-to-end ID	The end-to-end ID format is invalid. Please use a valid end-to-end identifier.

Returns

`code`	Description	`detail`
`PIX-1037`	400 Return not allowed	Return is not allowed for this transaction. Please check the transaction status and return eligibility.
`PIX-1038`	422 Invalid return reason	The return reason code is invalid. Please use a valid return reason code.
`PIX-1039`	422 Return amount exceeds original	The return amount exceeds the original transaction amount. Please enter a valid return amount.
`PIX-1040`	400 Return window expired	The return window has expired for this transaction. Returns are no longer allowed.
`PIX-1041`	404 Original transaction not found	The original transaction was not found for this return. Please verify the transaction identifier.

Participants and accounts

`code`	Description	`detail`
`PIX-1042`	422 Invalid bank ID	The Bank ID code is invalid. Please provide a valid Bank ID code.
`PIX-1043`	422 Bank ID not participating	The Bank ID is not participating in the PIX system. Please use a participating Bank ID.
`PIX-1044`	422 Invalid account number	The account number format is invalid. Please provide a valid account number.
`PIX-1045`	422 Account blocked	The account is blocked and cannot be accessed. Please contact support.
`PIX-1046`	400 Account closed	The account is closed and cannot be accessed. Please use an active account.

QR codes

`code`	Description	`detail`
`PIX-1047`	422 Invalid QR code	The QR code format is invalid or corrupted. Please verify the QR code and try again.
`PIX-1048`	404 QR code expired	The QR code has expired and cannot be used. Please generate a new QR code.
`PIX-1049`	422 QR code already used	The QR code has already been used and cannot be used again.

Rail availability

`code`	Description	`detail`
`PIX-1050`	503 JDPI service unavailable	JDPI service is temporarily unavailable. Please try again later.
`PIX-1051`	504 JDPI service timeout	JDPI service request timed out. Please try again.
`PIX-1052`	500 JDPI internal error	An internal JDPI error occurred. Please contact support if the issue persists.
`PIX-1053`	429 Too many requests	Too many requests have been sent. Please wait before making another request.
`PIX-1054`	400 JDPI connection error	Failed to connect to JDPI service. Please check service availability and try again.
`PIX-1055`	502 External service error	`internal error`

Fraud, compliance and regulation

`code`	Description	`detail`
`PIX-1056`	403 Fraud detected	The transaction was blocked due to fraud detection. Please contact support.
`PIX-1057`	403 Compliance violation	A compliance violation was detected. Please ensure all requirements are met.
`PIX-1058`	403 Regulatory restriction	A regulatory restriction applies to this operation. Please contact support.

Failures that originate outside the Pix rail

A Pix request can also fail because another platform service refused it. Three code bands carry those refusals: customer records, authorization, and the Midaz ledger.

Customer records

`code`	Description	`detail`
`PIX-2000`	422 Invalid metadata nesting	The metadata object cannot contain nested values. Please ensure that the value is not nested and try again.
`PIX-2001`	422 Metadata key too long	The metadata key exceeds the maximum allowed length. Please use a shorter key name.
`PIX-2002`	400 Missing fields in request	Your request is missing one or more required fields. Please provide all required fields and try again.
`PIX-2003`	400 Invalid field type in request	One or more fields have incorrect data types. Please check the field types and try again.
`PIX-2004`	400 Invalid path parameter	The path parameters are in incorrect format. Please verify the parameter format.
`PIX-2005`	400 Unexpected fields in the request	The request contains more fields than expected. Please send only the allowed fields as per the documentation.
`PIX-2006`	422 Pagination limit exceeded	The pagination limit exceeds the maximum allowed value. Please use a smaller limit.
`PIX-2007`	400 Invalid sort order	The sort order must be either “asc” or “desc”. Please use a valid sort order.
`PIX-2008`	400 Metadata value too long	The metadata value exceeds the maximum allowed length. Please use a shorter value.
`PIX-2009`	409 Account already associated	The account can only be associated with one related account. Please use a different account.
`PIX-2010`	400 Bad request	The server cannot understand the request due to invalid syntax. Please check the request format.
`PIX-2011`	400 Invalid query parameter	The query parameters are in incorrect format. Please verify the parameter values.
`PIX-2012`	422 Unable to delete holder	The holder cannot be deleted due to associated accounts. Please remove associated accounts first.
`PIX-2013`	400 Missing headers in request	Required header parameters are missing from the request. Please include all required headers.
`PIX-2014`	400 Invalid metadata format	The metadata parameter format is incorrect. Please use the correct metadata format.
`PIX-2015`	404 Holder ID not found	The specified holder ID does not exist. Please verify the holder ID and try again.
`PIX-2016`	404 Account ID not found	The specified account ID does not exist. Please verify the account ID and try again.
`PIX-2017`	403 CRM authentication failed	CRM authentication failed. Please verify your credentials.
`PIX-2018`	409 Document association error	The document can only be associated with one holder. Please use a different document.
`PIX-2019`	500 Internal server error	`internal error`
`PIX-2020`	503 CRM connection error	`internal error`
`PIX-2021`	504 CRM service timeout	`internal error`
`PIX-2022`	503 CRM service unavailable	`internal error`
`PIX-2023`	401 CRM authentication failed	CRM authentication failed. Please verify your credentials.
`PIX-2024`	429 CRM rate limit exceeded	CRM service rate limit exceeded. Please wait before making another request.

Authorization

`code`	Description	`detail`
`PIX-3000`	400 Missing fields in request	Your request is missing one or more required fields. Please provide all required fields and try again.
`PIX-3001`	422 Invalid grant type	The provided grant type is invalid. Please use “client_credentials” for authentication.
`PIX-3002`	422 Grant type missing fields	Required fields are missing for the grant type. Please provide client_id and client_secret.
`PIX-3003`	422 Unsupported grant type	The grant type is not supported by the application. Please use “client_credentials”.
`PIX-3004`	401 Invalid client	The provided client credentials are invalid. Please verify your client ID and client Secret.
`PIX-3005`	400 Bad request	The server cannot understand the request due to invalid syntax. Please check the request format.
`PIX-3006`	400 Access manager connection error	Failed to connect to Access Manager service. Please check service availability and try again.
`PIX-3007`	504 Access manager timeout	`internal error`
`PIX-3008`	503 Access manager service unavailable	`internal error`

Ledger

`code`	Description	`detail`
`PIX-4000`	503 Midaz connection error	`internal error`
`PIX-4001`	504 Midaz service timeout	`internal error`
`PIX-4002`	503 Midaz service unavailable	`internal error`
`PIX-4003`	401 Midaz authentication failed	Midaz authentication failed. Please verify your credentials.
`PIX-4004`	403 Midaz unauthorized access	Unauthorized access to Midaz service. Please check your permissions.
`PIX-4005`	400 Invalid Midaz request	Invalid request to Midaz service. Please verify the request format.
`PIX-4006`	404 Midaz account not found	The specified Midaz account was not found. Please verify the account ID and try again.
`PIX-4007`	422 Midaz account blocked	The Midaz account is blocked and cannot be accessed. Please contact support.
`PIX-4008`	400 Midaz account closed	The Midaz account is closed and cannot be accessed. Please contact support.
`PIX-4009`	422 Insufficient Midaz balance	The account does not have sufficient balance for this operation. Please add funds and try again.
`PIX-4010`	503 Midaz balance fetch error	`internal error`
`PIX-4011`	500 Midaz transaction failed	`internal error`
`PIX-4012`	500 Midaz debit failed	`internal error`
`PIX-4013`	500 Midaz credit failed	`internal error`
`PIX-4014`	404 Midaz transaction not found	The specified Midaz transaction was not found. Please verify the transaction ID.
`PIX-4015`	409 Duplicate Midaz transaction	A Midaz transaction with this identifier already exists. Please use a unique transaction ID.
`PIX-4016`	422 Invalid transaction amount	The transaction amount is invalid. Please provide a valid positive amount.
`PIX-4017`	409 Midaz transaction limit exceeded	The transaction amount exceeds Midaz configured limits. Please try a smaller amount.

Notification delivery

The Pix key ownership flows send a one-time code by email or by SMS. These codes report a failure on that delivery leg.

Email delivery

`code`	Description	`detail`
`PIX-5000`	401 Invalid API key	The SendGrid API key is invalid, deleted, or permissions have changed. Please verify your API key.
`PIX-5001`	400 Malformed payload	The SendGrid API payload request is malformed. Please check the request format.
`PIX-5002`	403 Insufficient permissions	You have insufficient permissions for this SendGrid operation. Please check your account permissions.
`PIX-5003`	429 Rate limit exceeded	SendGrid rate limit exceeded. Please wait before making another request.
`PIX-5004`	400 SendGrid connection error	Failed to connect to SendGrid email service. Please check service availability and try again.
`PIX-5005`	504 SendGrid service timeout	SendGrid email service request timed out. Please try again.
`PIX-5006`	503 SendGrid service unavailable	SendGrid email service is temporarily unavailable. Please try again later.

SMS delivery

`code`	Description	`detail`
`PIX-6000`	403 Permission denied	Permission denied for Twilio SMS operation. Please check your account permissions and try again.
`PIX-6001`	401 Invalid access token	The Twilio access token is invalid. Please verify your authentication credentials.
`PIX-6002`	401 Authentication failed	Twilio SMS authentication failed. Please verify your account credentials.
`PIX-6003`	400 Trial account limitation	This feature is not available for trial accounts. Please upgrade your Twilio account.
`PIX-6004`	400 Invalid URL format	Invalid URL format for Twilio webhook. Please verify the URL format and try again.
`PIX-6005`	400 HTTP protocol violation	HTTP protocol violation in Twilio request. Please check the request format.
`PIX-6006`	429 SMS rate limit exceeded	Twilio SMS send rate limit exceeded. Please wait before sending more messages.
`PIX-6007`	400 Phone not SMS capable	The from phone number is not SMS capable. Please use an SMS-capable phone number.
`PIX-6008`	400 Reply limit exceeded	TwiML Reply message limit exceeded. Please reduce the number of reply messages.
`PIX-6009`	400 Verb used for the SMS request is not allowed	Invalid Verb for SMS Reply. Please use a valid TwiML verb.
`PIX-6010`	400 Invalid phone for trial	Invalid destination phone number for trial mode. Please verify the number or upgrade your account.
`PIX-6011`	400 Sender phone number is not verified	The from phone number is not verified for your Twilio account. Please verify the number.
`PIX-6012`	400 Sender phone number is not verified	The from phone number is not verified for your Twilio account. Please verify the number.
`PIX-6013`	400 Invalid destination phone number	The destination phone number format is invalid. Please use a valid phone number.
`PIX-6014`	400 Invalid sender phone number	The sender phone number format is invalid. Please use a valid phone number.
`PIX-6015`	400 Twilio connection error	Failed to connect to Twilio SMS service. Please check service availability and try again.
`PIX-6016`	504 Twilio service timeout	Twilio SMS service request timed out. Please try again.
`PIX-6017`	503 Twilio service unavailable	Twilio SMS service is temporarily unavailable. Please try again later.

MED refund rejection reasons

A MED refund request that this participant analyzes and rejects carries a numbered rejection reason. The domain uses the values 0, 1, 3 and 4.

Value	Label	What it means
`0`	Falta de saldo	The customer account does not hold the balance to fund the refund.
`1`	Relacionamento encerrado	The relationship with the customer is closed.
`3`	Generico	A reason the other three values do not cover.
`4`	Requisicao invalida	The refund request is invalid. This value applies when the refund reason is an operational failure.

Pix return reason codes

A returned Pix carries a Bacen return reason of its own, separate from the PIX-NNNN codes above. This API reference documents the allowed values on the field that carries them. That field is codigoDevolucao on an inbound credit and on the refund credit status view. On a refund request it is code.

​Pix service request and business rules

​Request validation and access

​Pix keys

​Pix key claims

​Transactions and payments

​Returns and refunds

​Participants and accounts

​QR codes

​Entities, templates and conciliation

​Fraud, compliance and regulation

​Service and dependency faults

​Tenant configuration

​Indirect participants

​Inbound credits

​Pix rail and key directory

​Request validation and authentication

​Pix keys

​Pix key claims

​Transactions and payments

​Returns

​Participants and accounts

​QR codes

​Rail availability

​Fraud, compliance and regulation

​Failures that originate outside the Pix rail

​Customer records

​Authorization

​Ledger

​Notification delivery

​Email delivery

​SMS delivery

​MED refund rejection reasons

​Pix return reason codes

Pix service request and business rules

Request validation and access

Pix keys

Pix key claims

Transactions and payments

Returns and refunds

Participants and accounts

QR codes

Entities, templates and conciliation

Fraud, compliance and regulation

Service and dependency faults

Tenant configuration

Indirect participants

Inbound credits

Pix rail and key directory

Request validation and authentication

Pix keys

Pix key claims

Transactions and payments

Returns

Participants and accounts

QR codes

Rail availability

Fraud, compliance and regulation

Failures that originate outside the Pix rail

Customer records

Authorization

Ledger

Notification delivery

Email delivery

SMS delivery

MED refund rejection reasons

Pix return reason codes