> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Pix JD error list
> Look up a PIX-NNNN code in the Pix JD catalog, the condition behind it, and the detail text the response carries.
**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.
```json JSON theme={null}
{
"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/`.
* **`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`.