> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://en.docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://en.docs.api.corpx.com/_mcp/server.

# Errors

Every error response has the same body. Branch on `errorCode`, never on
`message` — the text is presentation and may change; the code is contract.

```json
{
  "errorCode": "insufficient_funds",
  "message": "Saldo insuficiente para concluir a operação.",
  "docs": "https://docs.api.corpx.com/baas/guias/referencia/erros#insufficient_funds",
  "requestId": "3f7c2a9e-1b4d-4c8e-9f0a-2b6d7e8f9a0b",
  "partner": { "code": "INSUFFICIENT_BALANCE", "message": "Saldo insuficiente" }
}
```

| Field       | What it is                                                                         |
| ----------- | ---------------------------------------------------------------------------------- |
| `errorCode` | Stable code. The list below is generated from the gateway source on every release. |
| `message`   | Portuguese explanation for logs and support. Do not parse it.                      |
| `docs`      | Link to the code's anchor on this page.                                            |
| `requestId` | Gateway request id. Quote it when opening a ticket.                                |
| `partner`   | Only when the failure came from the settlement bank: its raw error, for diagnosis. |

> **Open enum**
>
> New codes may appear without a version bump. Treat an unknown `errorCode`
> as a generic error of the same HTTP status: 4xx means the request is wrong
> (do not retry unchanged); 5xx and `retryable: yes` can be retried with the
> same `Idempotency-Key`.

## General

Authentication, headers, format and availability. Can happen on any route.

| Code                                   | HTTP | What happened and what to do                                                                                                                                                                                                                                                                                                                          | Retryable |
| -------------------------------------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `account_blocked`                      | 423  | The account was operationally blocked by CorpX. Queries and incoming funds remain available, but outgoing financial operations are refused until it is unblocked.                                                                                                                                                                                     | no        |
| `account_has_balance`                  | 422  | `POST /v1/accounts/{accountId}/close` on the exclusive path: the settlement bank still holds an available balance (`available` ≠ 0, or `total` ≠ 0 with nothing locked). Withdraw it first. The body carries the raw settlement-bank balance.                                                                                                         | no        |
| `account_has_locked_balance`           | 422  | `POST /v1/accounts/{accountId}/close` on the exclusive path: the available balance is zero, but the settlement bank still holds a locked balance (`locked` ≠ 0, e.g. a MED hold). The account can only be closed after the lock is released. The body carries the raw settlement-bank balance.                                                        | no        |
| `account_has_pix_keys`                 | 422  | `POST /v1/accounts/{accountId}/close` on the exclusive path: the account still has a PIX key at the settlement bank. Delete the keys first. The body lists key types only, not the key value.                                                                                                                                                         | no        |
| `account_holder_missing`               | 404  | The settlement bank did not return the account holder.                                                                                                                                                                                                                                                                                                | no        |
| `account_not_found`                    | 404  | The `accountId` in the path does not exist.                                                                                                                                                                                                                                                                                                           | no        |
| `acting_not_holder`                    | 403  | X-Acting-Document is not the account holder's document.                                                                                                                                                                                                                                                                                               | no        |
| `bank_not_found`                       | 404  | `GET /v1/banks/{code}` did not find that COMPE or ISPB in the catalog (or the row is disabled).                                                                                                                                                                                                                                                       | no        |
| `banking_unavailable`                  | 503  | The banking provider is not available for this operation right now. Retry in a few seconds; nothing was executed.                                                                                                                                                                                                                                     | yes       |
| `beneficiary_check_unavailable`        | 503  | Could not confirm the internal-transfer destination by document. Retry or use `/transfers/internal/by-bank-account`.                                                                                                                                                                                                                                  | no        |
| `cognito_error`                        | 502  | Identity provider failure while creating or changing the credential. Retry; if it persists, contact support.                                                                                                                                                                                                                                          | yes       |
| `cognito_unavailable`                  | 503  | Identity provider unavailable. Retry shortly.                                                                                                                                                                                                                                                                                                         | yes       |
| `credential_revoked`                   | 403  | The credential used has been revoked. Issue a new one in the internet banking (IB) or with CorpX (BaaS).                                                                                                                                                                                                                                              | no        |
| `db_error`                             | 500  | Internal persistence error.                                                                                                                                                                                                                                                                                                                           | no        |
| `db_unavailable`                       | 503  | Gateway database unavailable. Nothing was executed; retry shortly.                                                                                                                                                                                                                                                                                    | yes       |
| `evidence_not_approved`                | 422  | The biometry evidence (`biometry.evidenceId`) has not passed content verification yet, or was rejected. Upload new evidence.                                                                                                                                                                                                                          | no        |
| `forbidden`                            | 403  | You do not have permission to perform this action on the requested resource.                                                                                                                                                                                                                                                                          | no        |
| `holder_not_pj`                        | 422  | A holder update is only for a company account. A person uses PUT /holder/address.                                                                                                                                                                                                                                                                     | no        |
| `holder_update_closed`                 | 409  | The request is not in a state that accepts this action.                                                                                                                                                                                                                                                                                               | no        |
| `holder_update_document_type_invalid`  | 422  | documentType is not part of this request.                                                                                                                                                                                                                                                                                                             | no        |
| `holder_update_documents_missing`      | 422  | A required document with scanStatus APPROVED is missing.                                                                                                                                                                                                                                                                                              | no        |
| `holder_update_kind_invalid`           | 422  | kind must be address or registration.                                                                                                                                                                                                                                                                                                                 | no        |
| `holder_update_not_found`              | 404  | Holder update not found on this account.                                                                                                                                                                                                                                                                                                              | no        |
| `holder_update_pending`                | 409  | An open request of the same kind already exists for this account.                                                                                                                                                                                                                                                                                     | no        |
| `holder_update_required`               | 422  | A company account cannot change its address directly. Open a holder update with proof of address.                                                                                                                                                                                                                                                     | no        |
| `idempotency_conflict`                 | 409  | The `Idempotency-Key` was already used by another tenant on an endpoint that derives identifiers from it (flows enabled on request). Reusing an `Idempotency-Key` with a different body does **not** return a conflict on the other endpoints: you get the result of the original operation. See [Idempotency](/baas/guias/comece-aqui/idempotencia). | no        |
| `identity_not_approved`                | 409  | Identity verification for the consent journey is not approved yet. The journey stays pending; the holder recaptures via the same link.                                                                                                                                                                                                                | no        |
| `identity_stale`                       | 409  | Identity verification expired. The journey stays pending; the holder recaptures via the same link.                                                                                                                                                                                                                                                    | no        |
| `ingest_unavailable`                   | 503  | Internal ingestion component unavailable. Retry shortly.                                                                                                                                                                                                                                                                                              | yes       |
| `init_error`                           | 500  | Failed to initialise gateway dependencies. Retry; if it persists, contact support with the `requestId`.                                                                                                                                                                                                                                               | yes       |
| `insufficient_scope`                   | 403  | The credential lacks the **scope** required by the route (e.g. `qrcode.manage`, `pix_out.create`), or is read-only attempting a write. The message names the missing scope. See the [Authentication Guide](/baas/guias/autenticacao/oauth2).                                                                                                          | no        |
| `integrator_credential_required`       | 403  | The route moves money and requires an integrator credential (`client_credentials`) issued by CorpX. A Portal user session token is refused even when that user has access to the account.                                                                                                                                                             | no        |
| `internal_error`                       | 500  | An unexpected error occurred on our servers.                                                                                                                                                                                                                                                                                                          | no        |
| `invalid_account`                      | 400  | The `accountId` given for the credential is not a UUID or does not belong to the tenant.                                                                                                                                                                                                                                                              | no        |
| `invalid_body`                         | 400  | The body is not valid JSON.                                                                                                                                                                                                                                                                                                                           | no        |
| `invalid_client`                       | 400  | Malformed `clientId`.                                                                                                                                                                                                                                                                                                                                 | no        |
| `invalid_path`                         | 400  | A path segment is empty or malformed (for example a missing `transactionId` on the timeline route).                                                                                                                                                                                                                                                   | no        |
| `invalid_scope`                        | 400  | One of the scopes requested for the credential does not exist. See the list under Authentication.                                                                                                                                                                                                                                                     | no        |
| `invalid_state`                        | 409  | The operation does not apply to the resource's current state.                                                                                                                                                                                                                                                                                         | no        |
| `marshal_error`                        | 500  | Internal failure while serialising the response. Retry; if it persists, contact support with the `requestId`.                                                                                                                                                                                                                                         | yes       |
| `med_request_closed`                   | 409  | The contestation is not in a state that accepts this action.                                                                                                                                                                                                                                                                                          | no        |
| `med_request_info_missing`             | 422  | Resubmitting after an information request requires a message or an approved attachment.                                                                                                                                                                                                                                                               | no        |
| `med_request_not_found`                | 404  | Contestation not found on this account.                                                                                                                                                                                                                                                                                                               | no        |
| `med_request_not_outgoing_pix`         | 422  | Only a PIX sent by this account can be contested.                                                                                                                                                                                                                                                                                                     | no        |
| `med_request_out_of_window`            | 422  | The PIX is outside the 80-day contestation window.                                                                                                                                                                                                                                                                                                    | no        |
| `med_request_pending`                  | 409  | An open contestation already exists for this endToEndId.                                                                                                                                                                                                                                                                                              | no        |
| `method_not_allowed`                   | 405  | The HTTP method is not accepted on this route. Check the method in the API reference.                                                                                                                                                                                                                                                                 | no        |
| `missing_idempotency_key`              | 400  | The Idempotency-Key header is required.                                                                                                                                                                                                                                                                                                               | no        |
| `missing_tenant`                       | 400  | The `X-Tenant-Id` header is required and was not provided.                                                                                                                                                                                                                                                                                            | no        |
| `no_accounts`                          | 404  | The tenant has no accounts yet. Finish account opening before operating.                                                                                                                                                                                                                                                                              | no        |
| `payload_too_large`                    | 413  | Request body exceeds the route limit (MED evidence: 10 MB). Shrink the file or use the upload URL.                                                                                                                                                                                                                                                    | no        |
| `pix_transaction_not_found`            | 404  | The endToEndId is not a PIX of this account.                                                                                                                                                                                                                                                                                                          | no        |
| `rate_check_unavailable`               | 503  | Could not validate the journey rate limit right now. Retry in a moment.                                                                                                                                                                                                                                                                               | no        |
| `request_in_progress`                  | 409  | The same `Idempotency-Key` is already being processed for this tenant. Wait and retry; this is not a second close.                                                                                                                                                                                                                                    | yes       |
| `scope_not_self_service`               | 403  | This scope can only be granted by CorpX, not by the credential itself.                                                                                                                                                                                                                                                                                | no        |
| `storage_error`                        | 502  | Failed to store or read the evidence file. Retry; if it persists, contact support.                                                                                                                                                                                                                                                                    | yes       |
| `temporal_unavailable`                 | 503  | The async operation orchestrator did not respond; the operation was not started. Retry with the same `Idempotency-Key`.                                                                                                                                                                                                                               | yes       |
| `tenant_disabled`                      | 403  | The tenant is disabled: no API route responds. Contact CorpX support to restore access.                                                                                                                                                                                                                                                               | no        |
| `tenant_forbidden`                     | 403  | The token is not authorized for the tenant in `X-Tenant-Id`. Applies to every `/v1/` route: credential and header must point to the same tenant.                                                                                                                                                                                                      | no        |
| `tenant_mismatch`                      | 403  | `X-Tenant-Id` does not match the tenant of the account in the path (or the body's `tenantId`).                                                                                                                                                                                                                                                        | no        |
| `tenant_suspended`                     | 403  | There is an open pendency and **write** operations are suspended. Reads keep working. Contact CorpX support to clear it.                                                                                                                                                                                                                              | no        |
| `unauthorized`                         | 401  | Missing `Authorization` header. **An invalid or expired token returns `403`** (obtain a new token via `client_credentials`).                                                                                                                                                                                                                          | no        |
| `unsupported_media_type`               | 422  | File type not accepted as MED evidence. Send PDF, PNG or JPEG.                                                                                                                                                                                                                                                                                        | no        |
| `user_token_forbidden_on_financial_op` | 403  | User tokens cannot move money: financial operations require an application credential (`client_credentials`).                                                                                                                                                                                                                                         | no        |
| `workflow_start_failed`                | 500  | The asynchronous operation could not be started. Retry with the same `Idempotency-Key`; if it persists, contact support.                                                                                                                                                                                                                              | yes       |
| `workflow_timeout`                     | 504  | The operation did not finish inside the synchronous window. The outcome is indeterminate: check the statement or status before retrying.                                                                                                                                                                                                              | no        |

## Settlement bank

Rejections from the settlement bank translated to stable codes. The `partner` block carries the original.

| Code                                              | HTTP | What happened and what to do                                                                                                                                                                                                                                                                                        | Retryable |
| ------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `account_not_entitled`                            | 409  | The account is fully accredited, but the banking provider has not enabled this service for it — other operations on the same account keep working. This is neither a transient failure nor a problem with your request: retrying will not help until the provider enables it. Contact support with the `accountId`. | no        |
| `account_not_ready`                               | 409  | The account has no counterpart at the banking provider yet — accreditation is in progress, was refused, or never completed. This is not an API outage: no banking operation works on this account until the accreditation reaches `ACTIVE`.                                                                         | no        |
| `already_at_partner`                              | 409  | The document is already accredited at the banking provider by another participant. Requires a control transfer through support.                                                                                                                                                                                     | no        |
| `automatic_pix_contract_blocked`                  | 409  | The arrangement blocks the same contract within 24 hours, a pending authorization for the same contract and payer, and an identical proposal rejected or canceled less than 30 days ago. Wait for the payer or use another contract number.                                                                         | no        |
| `automatic_pix_date_out_of_window`                | 422  | A scheduling due date must fall in the current cycle at least 2 days ahead; a retry must be after the original due date, within 7 calendar days and the same cycle. Fetch the suggested dates before requesting a retry.                                                                                            | no        |
| `automatic_pix_identifier_in_use`                 | 409  | The composite QR Code identifier was already used on this account. Each composite QR needs its own identifier.                                                                                                                                                                                                      | no        |
| `automatic_pix_payer_bank_unavailable`            | 422  | The informed ISPB does not exist or is not active for Automatic Pix. Check the payer's bank.                                                                                                                                                                                                                        | no        |
| `automatic_pix_receiver_ineligible`               | 422  | The Automatic Pix receiver must be an active legal entity with complete bank data at the settlement bank.                                                                                                                                                                                                           | no        |
| `automatic_pix_recurrence_not_authorized`         | 409  | Schedulings, postponements and retries only apply to a recurrence with status authorized.                                                                                                                                                                                                                           | no        |
| `automatic_pix_retry_not_allowed`                 | 409  | A retry requires paymentRetry=true on the recurrence, an unsettled settlement, no attempt in progress on the same day and unused dates, up to 3.                                                                                                                                                                    | no        |
| `automatic_pix_scheduling_conflict`               | 409  | Each cycle accepts one active scheduling. Postponing only works while the scheduling is created.                                                                                                                                                                                                                    | no        |
| `automatic_pix_value_above_payer_limit`           | 422  | In a variable-amount recurrence, each charge respects the proposal maximumValue and the payerMaximumValue set by the payer.                                                                                                                                                                                         | no        |
| `automatic_pix_value_mismatch`                    | 422  | A fixed-amount recurrence charges exactly value; a variable one requires value on the scheduling. On creation, value and maximumValue are mutually exclusive.                                                                                                                                                       | no        |
| `bacen_rejected_content`                          | 400  | Text content (description/message) contains a character the Brazilian Central Bank does not accept.                                                                                                                                                                                                                 | no        |
| `balance_reservation_failed`                      | 422  | Balance reservation failed (funds locked, settling, or racing with another operation).                                                                                                                                                                                                                              | no        |
| `boleto_already_settled`                          | 409  | The bank slip is already settled. Check the original payment before resending.                                                                                                                                                                                                                                      | no        |
| `boleto_amount_mismatch`                          | 422  | Amount differs from the registered bank slip amount (consider interest, fine and discount).                                                                                                                                                                                                                         | no        |
| `boleto_charge_barcode_active`                    | 409  | Rejected because a bank slip with this barcode is still active.                                                                                                                                                                                                                                                     | no        |
| `boleto_charge_beneficiary_ineligible`            | 422  | The beneficiary is ineligible or under review. Retrying will not help until that changes.                                                                                                                                                                                                                           | no        |
| `boleto_charge_discount_invalid`                  | 422  | Discount limitDate is missing, unreadable, or not before the due date.                                                                                                                                                                                                                                              | no        |
| `boleto_charge_identifier_in_use`                 | 409  | Issuance was rejected because the identifier is already active for this beneficiary.                                                                                                                                                                                                                                | no        |
| `boleto_charge_not_eligible_for_write_off_cancel` | 409  | Cancelling a write-off requires status writtenOff with a write-off in the arrangement. It does not cancel an open slip.                                                                                                                                                                                             | no        |
| `boleto_charge_reductions_exceed_amount`          | 422  | Abatement plus discounts reach or exceed the face amount.                                                                                                                                                                                                                                                           | no        |
| `boleto_charge_rules_inconsistent`                | 422  | A charge is inconsistent with the calculation model, or the min/max payment amounts disagree.                                                                                                                                                                                                                       | no        |
| `boleto_scheduled`                                | 409  | There is an active schedule for the same barcode.                                                                                                                                                                                                                                                                   | no        |
| `challenge_failure`                               | 422  | PIN/2FA validation failed at the banking provider.                                                                                                                                                                                                                                                                  | no        |
| `conflict`                                        | 409  | State conflict at the banking provider (e.g. resource already processed).                                                                                                                                                                                                                                           | no        |
| `identifier_conflict`                             | 409  | The `Identifier` was already used at the banking provider. Resending the same value does not create a new operation.                                                                                                                                                                                                | no        |
| `insufficient_funds`                              | 422  | Insufficient balance as computed by the banking provider at settlement time.                                                                                                                                                                                                                                        | no        |
| `invalid_field`                                   | 400  | Field-level validation at the banking provider. `partner.field` names the field and the message carries the limit when available.                                                                                                                                                                                   | no        |
| `invalid_payload`                                 | 400  | The banking provider rejected the request body. The `partner` block carries the original validation message.                                                                                                                                                                                                        | no        |
| `invalid_pix_key`                                 | 400  | Key format does not match the declared type (`CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`).                                                                                                                                                                                                                               | no        |
| `key_inactive`                                    | 422  | The key exists but is inactive or under portability. Use another key or bank details.                                                                                                                                                                                                                               | no        |
| `key_not_found`                                   | 404  | Key not found in DICT. Check for typos or ask the recipient for another key.                                                                                                                                                                                                                                        | no        |
| `key_ownership_mismatch`                          | 422  | Attempt to register or use a key whose document differs from the account holder's.                                                                                                                                                                                                                                  | no        |
| `limit_exceeded`                                  | 422  | A limit was exceeded but the provider did not say which window.                                                                                                                                                                                                                                                     | no        |
| `limit_exceeded_daily`                            | 422  | For PIX, daytime window limit (06:00–20:00). For an internal transfer, São Paulo calendar-day limit (00:00–23:59). The message carries the remaining amount when available.                                                                                                                                         | no        |
| `limit_exceeded_monthly`                          | 422  | Accumulated monthly limit. Only clears at month rollover or with a limit increase.                                                                                                                                                                                                                                  | no        |
| `limit_exceeded_nightly`                          | 422  | Nighttime window limit (20:00–06:00), usually lower than the daytime one.                                                                                                                                                                                                                                           | no        |
| `limit_exceeded_transaction`                      | 422  | Per-transaction limit. Split the operation or request a limit increase.                                                                                                                                                                                                                                             | no        |
| `not_found`                                       | 404  | Resource does not exist at the banking provider (id, key or transaction).                                                                                                                                                                                                                                           | no        |
| `not_supported`                                   | 501  | The route exists in the contract, but the settlement provider does not expose the operation. Retrying will not help — it is a missing capability, not an outage.                                                                                                                                                    | no        |
| `partial_refund_not_supported`                    | 400  | Legacy — no longer returned: partial refunds are now accepted. An amount above the original returns `refund_amount_exceeded`.                                                                                                                                                                                       | no        |
| `partner_account_disabled`                        | 422  | Source account is disabled at the banking provider (reactivation required).                                                                                                                                                                                                                                         | no        |
| `partner_error`                                   | 502  | Unclassified failure while talking to the banking provider. Safe to retry.                                                                                                                                                                                                                                          | yes       |
| `partner_forbidden`                               | 502  | Operation blocked by the banking provider for this account (product or permission not enabled).                                                                                                                                                                                                                     | no        |
| `partner_internal`                                | 502  | Internal (5xx) error at the banking provider. Safe to retry.                                                                                                                                                                                                                                                        | yes       |
| `partner_rate_limited`                            | 429  | The banking provider throttled CorpX's traffic. Nothing is wrong with your request — slow down and retry with backoff.                                                                                                                                                                                              | yes       |
| `partner_rejected`                                | 422  | Refused by the banking provider on internal policy, risk or fraud grounds. The `partner` block carries the stated reason.                                                                                                                                                                                           | no        |
| `partner_unauthorized`                            | 502  | CorpX's own credential at the banking provider was rejected. Not related to your credential; wait a few minutes before resending.                                                                                                                                                                                   | no        |
| `partner_unavailable`                             | 502  | Provider outage or gateway failure. Safe to retry.                                                                                                                                                                                                                                                                  | yes       |
| `payer_key_required`                              | 422  | The paying account needs at least one active PIX key to send. The problem is the source account, not the recipient's key: register a key (a random key works) and retry.                                                                                                                                            | no        |
| `pix_key_limit_exceeded`                          | 422  | Maximum number of keys per account reached (5 for individuals, 20 for companies).                                                                                                                                                                                                                                   | no        |
| `qr_amount_mismatch`                              | 422  | A fixed-amount QR Code does not accept a different amount.                                                                                                                                                                                                                                                          | no        |
| `qr_gone`                                         | 409  | QR Code removed or expired at the banking provider.                                                                                                                                                                                                                                                                 | no        |
| `recipient_account_not_found`                     | 422  | Destination bank/branch/account does not exist. Applies to TED and internal transfers.                                                                                                                                                                                                                              | no        |
| `refund_amount_exceeded`                          | 400  | Refund amount is larger than the refundable balance of the original PIX.                                                                                                                                                                                                                                            | no        |
| `timeout`                                         | 504  | Timeout calling the banking provider. The operation may exist — query it before resending.                                                                                                                                                                                                                          | yes       |

## PIX out

| Code                                                                                  | HTTP | What happened and what to do                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Retryable |
| ------------------------------------------------------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `batch_not_found`                                                                     | 404  | BigPix: the requested `batchId` does not exist.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | no        |
| `batch_too_large`                                                                     | 400  | BigPix: the requested amount would produce more than 99 chunks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | no        |
| `beneficiary_incomplete`                                                              | 422  | The stored beneficiary lacks data required by the chosen operation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | no        |
| `beneficiary_not_active_at_partner`                                                   | 422  | The beneficiary exists locally but is not active at the provider yet.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | no        |
| `beneficiary_not_found`                                                               | 404  | The given beneficiary does not exist in the account's address book.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | no        |
| `dict_lookup_limit_exceeded`                                                          | 429  | DICT lookup limits were exceeded: either an absolute count (`maxLookupsPerDay`, `maxLookupsPerMinute`, `maxNotFoundPer5min`) or a rate over a time window (lookups per transfer, or the fraction of lookups resolving no key, from 5 min to 30 days). Both the tenant/account policy and, for fields left blank, the global default apply — always counted **per account**, never summed across the tenant. The message indicates which counter or window triggered. Wait for the window to reset (00:00 BRT for per-day; sliding for the rates) or adjust the limits in the Backoffice. Abusive consumption is monitored and has consequences — see [PIX key lookups](/baas/guias/pagar/consulta-dict). | no        |
| `invalid_amount`                                                                      | 400  | `amount` missing, not positive, or with more than two decimal places.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | no        |
| `invalid_bank_code`                                                                   | 400  | On PIX by bank-account details, `bankCode` accepts a 3-digit Compe code or an 8-digit ISPB. TED accepts only the Compe code — see [TED](#ted).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | no        |
| `invalid_identifier`                                                                  | 400  | `identifier` exceeds the accepted length, uses disallowed characters, or — on a limit increase — is not identical to the `Idempotency-Key` header.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | no        |
| `invalid_pix_batch_policy`                                                            | 400  | pixBatch.maxItems must be an integer between 1 and 5000 and pixBatch.enabled must be a boolean.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | no        |
| `pix_batch_account_disabled`                                                          | 403  | Batch PIX is not enabled for this account. pixBatch.enabled=true on the tenant policy enables every account; on the account policy, only that account. Set by CorpX staff.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | no        |
| \<a id="pix_batch_acknowledgement_required">\</a>`pix_batch_acknowledgement_required` | 409  | Dispatch requires \{"acknowledged": true} confirming the review summary (amounts, balance and limits) was read.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | no        |
| `pix_batch_chunk_invalid`                                                             | 400  | Each items PUT must contain between 1 and 50 valid payments; the body lists the rejected rows in errors\[] and nothing was saved.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | no        |
| `pix_batch_csv_invalid`                                                               | 400  | The CSV does not follow the template (header, separator or invalid rows) or exceeds 5 MiB (413). errors\[] points to line and field; nothing was saved.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | no        |
| `pix_batch_empty`                                                                     | 409  | The batch has no items to review or dispatch.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | no        |
| `pix_batch_has_invalid_items`                                                         | 409  | Review flagged invalid items (missing key, identifier already used, above the per-operation limit…). Download the correction CSV from GET .../items/export?status=invalid, fix or remove them and review again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | no        |
| `pix_batch_insufficient_balance`                                                      | 422  | The available balance at dispatch time is lower than the batch total. No item was started.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | no        |
| `pix_batch_item_conflict`                                                             | 409  | The identifier already exists in the batch with different content. Repeating the same identifier with the same content is a no-op.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | no        |
| `pix_batch_item_not_found`                                                            | 404  | PIX batch item not found.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | no        |
| `pix_batch_limit_exceeded`                                                            | 422  | The review showed the batch total exceeds an account outbound limit (review\.limits with sufficient=false). Without this refusal the first PIX would go out and the rest would fail on the limit. Remove items or wait for the limit window and review again. No item was started.                                                                                                                                                                                                                                                                                                                                                                                                                       | no        |
| `pix_batch_no_receipts`                                                               | 409  | Receipts only exist for finished batches (COMPLETED, PARTIAL_FAILED or FAILED) with at least one settled item.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | no        |
| `pix_batch_not_editable`                                                              | 409  | Only DRAFT or REVIEWED batches accept item changes or a new review. After dispatch the batch is immutable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | no        |
| `pix_batch_not_found`                                                                 | 404  | PIX batch not found in this account.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | no        |
| `pix_batch_not_reviewed`                                                              | 409  | Dispatch requires a REVIEWED batch with every item checked. Call POST .../review and wait for the status.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | no        |
| `pix_batch_receipt_unavailable`                                                       | 409  | The item has not settled yet (or failed); only COMPLETED items have a receipt.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | no        |
| `pix_batch_too_large`                                                                 | 400  | The batch exceeds the account's maximum item count (pixBatch.maxItems; default 50, hard cap 5,000). The message carries the effective limit and its source.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | no        |
| `policy_denied`                                                                       | 422  | A policy rule configured for the account or tenant refused the operation — transfer, QR code creation, PIX key creation, or refund. The body carries `violations` with the `rule` and `message` of each violated rule. See [Policies and Rules](/baas/guias/autenticacao/politicas).                                                                                                                                                                                                                                                                                                                                                                                                                     | no        |
| `receipt_render_failed`                                                               | 500  | Failed to render the receipt PDF. Retry; the payment itself is not affected.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | yes       |

## QR Code

| Code            | HTTP | What happened and what to do                                                 | Retryable |
| --------------- | ---- | ---------------------------------------------------------------------------- | --------- |
| `missing_field` | 400  | `pixKey` missing — and, on dynamic QR, `value` missing or not positive.      | no        |
| `missing_param` | 400  | Lookup and cancellation require the `identifier` query param (alias `txid`). | no        |

## PIX keys

| Code                               | HTTP | What happened and what to do                                                                                                                        | Retryable |
| ---------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `key_type_temporarily_unavailable` | 422  | Registering an `email` or `phone` key is temporarily unavailable. Use `cpf`, `cnpj`, or `random`. Listing and deleting those key types still works. | no        |

## Refund

| Code                             | HTTP | What happened and what to do                                                                                                                                                                    | Retryable |
| -------------------------------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `med_info_missing`               | 422  | The clarification cannot be submitted without a new message or attachment since the review's request.                                                                                           | no        |
| `med_lock_unavailable`           | 409  | The balance hold could not be placed or released: an amount is already held, the dispute is closed, or the settlement bank refused the operation.                                               | no        |
| `med_not_found`                  | 404  | The dispute (MED) does not exist or does not belong to this account.                                                                                                                            | no        |
| `med_not_writable`               | 409  | The dispute accepts no message or attachment right now: only in `awaiting_defense` (before the answer) or in `info_requested`.                                                                  | no        |
| `med_opened_by_us`               | 409  | The MED was opened by CorpX on the customer's behalf (`direction: opened`): there is no defense, message, attachment or decision. Follow `partnerStatus` and `lastUpdatedAt` until the outcome. | no        |
| `med_refund_amount_invalid`      | 422  | The return amount is required, positive, and cannot exceed what is left to return (`remaining`).                                                                                                | no        |
| `med_refund_in_progress`         | 409  | A return for this dispute is still settling; wait for it to complete before the next step.                                                                                                      | no        |
| `med_refund_not_completed`       | 409  | The account is only released after the round's return is completed and the remainder held.                                                                                                      | no        |
| `med_review_not_pending`         | 409  | The action requires the dispute under review (`pending_review`) or with a pending clarification (`info_requested`); it has already moved on.                                                    | no        |
| `med_step_out_of_order`          | 409  | The requested step is not the next one in the round, or the dispute is not in execution. Return steps run one at a time, in order.                                                              | no        |
| `original_transaction_not_found` | 404  | The original transaction (`originalEndToEnd`) was not found.                                                                                                                                    | no        |

## TED

| Code                   | HTTP | What happened and what to do                                                                            | Retryable |
| ---------------------- | ---- | ------------------------------------------------------------------------------------------------------- | --------- |
| `invalid_account_type` | 400  | `accountType` must be `CHECKING`, `SAVINGS`, `PAYMENT` or `SALARY`. Omitted, it defaults to `CHECKING`. | no        |
| `invalid_tax_number`   | 400  | `taxNumber` must have 11 (CPF) or 14 (CNPJ) digits.                                                     | no        |
| `missing_fields`       | 400  | Missing `value`, `holderName`, `branch`, or `account`.                                                  | no        |

## Internal transfer

| Code                            | HTTP | What happened and what to do                                                                                                                                                                                                   | Retryable |
| ------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- |
| `multiple_destination_accounts` | 409  | On `/transfers/internal/by-document`, the document has more than one active account. Address it by account instead: `/transfers/internal/by-bank-account` (branch + number) or `/transfers/internal` (`destinationAccountId`). | no        |

## Statement, entries and exports

| Code                          | HTTP | What happened and what to do                                                                                                      | Retryable |
| ----------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `bucket_mismatch`             | 409  | The export file was produced in another environment and cannot be downloaded here. Create the export again.                       | no        |
| `date_range_too_wide`         | 400  | The statement window exceeds 31 days. Split it into smaller periods.                                                              | no        |
| `invalid_cursor`              | 400  | The pagination `cursor` is invalid or belongs to another query. Start over without `cursor`.                                      | no        |
| `invalid_date_range`          | 400  | `startDate` / `endDate` outside the `YYYY-MM-DD` format.                                                                          | no        |
| `invalid_filter`              | 400  | Invalid advanced statement filter (`type`, `direction`, `status`, `minAmount`/`maxAmount` or dates). The message names the field. | no        |
| `invalid_format`              | 400  | Export `format` must be `csv`, `pdf`, or `xlsx`.                                                                                  | no        |
| `invalid_operation`           | 400  | The entry detail requires the `operation` query param: `PIX`, `TED`, `BOLETO`, `INTERNAL`, or `FEE`.                              | no        |
| `invalid_query`               | 400  | The per-account timeline requires exactly one of `endToEndId` and `identifier` — never both, never neither.                       | no        |
| `invalid_s3_key`              | 500  | Internal reference to the export file is invalid. Create the export again; if it persists, contact support.                       | yes       |
| `missing_account_id`          | 400  | `accountId` missing from the path. Use `GET /v1/accounts/{accountId}/pix/payments/lookup?identifier=...`.                         | no        |
| `missing_identifier`          | 400  | Pass `identifier` or `endToEnd` in the query to locate the payment.                                                               | no        |
| `not_ready`                   | 409  | Download requested before the export finished. Poll the status until `completed`.                                                 | no        |
| `presign_failed`              | 500  | Failed to generate the download link for an already finished file. Safe to retry.                                                 | no        |
| `statement_rules_unavailable` | 503  | Statement presentation rules have not loaded yet. Balance and amount do not change; only labels. Retry shortly.                   | yes       |

## Webhooks

| Code                          | HTTP | What happened and what to do                                                                                                                                                         | Retryable |
| ----------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- |
| `account_id_required`         | 422  | The credential is restricted to specific accounts: pass `accountId` on the subscription. See [Per-account subscriptions](/baas/guias/conta/webhooks#assinatura-por-conta-accountid). | no        |
| `hookdeck_list_failed`        | 502  | The delivery service could not list the attempts. Retry shortly.                                                                                                                     | yes       |
| `hookdeck_retry_failed`       | 502  | The delivery service refused the retry. Retry shortly.                                                                                                                               | yes       |
| `hookdeck_source_unavailable` | 503  | The tenant's delivery source is unavailable in the webhook service. Retry shortly.                                                                                                   | yes       |
| `hookdeck_sync_failed`        | 502  | Failed to register the destination at our webhook delivery service. Safe to retry.                                                                                                   | no        |
| `hookdeck_unavailable`        | 503  | Webhook delivery service unavailable. Retry shortly.                                                                                                                                 | yes       |
| `invalid_url`                 | 400  | `url` must use `https://`.                                                                                                                                                           | no        |
| `missing_delivery_id`         | 400  | `deliveryId` missing from the path.                                                                                                                                                  | no        |
| `missing_subscription_id`     | 400  | `subscriptionId` missing from the path.                                                                                                                                              | no        |
| `no_hookdeck_destination`     | 410  | The subscription no longer has an active delivery destination. Recreate the subscription.                                                                                            | no        |
| `no_hookdeck_event_found`     | 410  | The delivery is past the retention window and can no longer be resent.                                                                                                               | no        |
| `reemit_failed`               | 500  | Failed to re-emit the event. Retry; if it persists, contact support with the `deliveryId`.                                                                                           | yes       |
| `replay_already_running`      | 409  | A replay is already running for this subscription. Wait for it to finish.                                                                                                            | no        |
| `unsupported_auth_type`       | 400  | Subscription `authType` outside the accepted values (`NONE`, `HMAC`, `BASIC`, `BEARER`).                                                                                             | no        |

## Request signing (signed host)

| Code                         | HTTP | What happened and what to do                                                                                                                                                 | Retryable |                             |    |
| ---------------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | --------------------------- | -- |
| `body_hash_mismatch`         | 400  | The received body does not match the signed `X-Content-SHA256`.                                                                                                              | no        |                             |    |
| `credential_not_yet_active`  | 403  | Freshly issued credential still inside its grace period. Wait for the `activeFrom` returned at issue time.                                                                   | no        |                             |    |
| `invalid_ip`                 | 400  | Invalid address or CIDR in the IP allowlist. Use IPv4/IPv6 or CIDR notation (`203.0.113.10/32`).                                                                             | no        |                             |    |
| `invalid_public_key`         | 422  | The PEM is not an EC P-256 or RSA ≥ 2048 public key. A **private** key PEM is rejected with its own message.                                                                 | no        |                             |    |
| `ip_allowlist_derived`       | 409  | The tenant has delegated credentials: its IP allowlist is derived from them and does not accept manual edits.                                                                | no        |                             |    |
| `ip_allowlist_required`      | 422  | `allowedIps` missing, empty, longer than 20 entries, containing `0.0.0.0/0` or a prefix wider than `/24`.                                                                    | no        |                             |    |
| `ip_not_allowed`             | 403  | The request came from an IP outside the credential's allowlist.                                                                                                              | no        |                             |    |
| `last_public_key`            | 409  | The credential's last usable key cannot be retired.                                                                                                                          | no        |                             |    |
| `public_key_limit_reached`   | 409  | Public key limit per credential reached. Retire one before adding another.                                                                                                   | no        |                             |    |
| `public_key_required`        | 422  | Issuing a delegated credential requires `publicKeyPem`.                                                                                                                      | no        |                             |    |
| `request_signature_invalid`  | 403  | The signature does not match the key announced in `kid`. Compare the canonical string via `POST /v1/security/signature/verify`; also check that the ES256 signature is \`R\\ | \\        | S\` (64 bytes) and not DER. | no |
| `request_signature_required` | 403  | Missing `X-Request-Signature`, `X-Request-Timestamp` or `X-Content-SHA256`.                                                                                                  | no        |                             |    |
| `request_timestamp_skew`     | 403  | `X-Request-Timestamp` outside the 300s window. Sync the server clock (NTP).                                                                                                  | no        |                             |    |
| `scope_not_delegable`        | 403  | The scope requested for the child credential is not held by the delegating credential, or is not delegable.                                                                  | no        |                             |    |
| `signature_required`         | 403  | The request reached `client.api.corpx.com` without the signature headers. Edge block, before the token is looked at.                                                         | no        |                             |    |
| `signed_host_required`       | 403  | A delegated credential was used on `tenant.api.corpx.com`. Retry on `client.api.corpx.com`, signed.                                                                          | no        |                             |    |
| `unknown_kid`                | 403  | The `kid` is not among the credential's active keys: it was retired, or it is still inside the 18h grace period.                                                             | no        |                             |    |

## Account security (locks, PIN and limits)

| Code                                           | HTTP | What happened and what to do                                                                                                                                                                                                                                                                                                                  | Retryable |
| ---------------------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `acting_document_required`                     | 400  | Send `X-Acting-Document` (the operator's CPF) together with the PIN.                                                                                                                                                                                                                                                                          | no        |
| `cashout_locked`                               | 423  | The account holder blocked money from leaving this account (`cashoutBlocked`).                                                                                                                                                                                                                                                                | no        |
| `cashout_outside_hours`                        | 403  | Outside the time window configured by the account holder. The message states the window.                                                                                                                                                                                                                                                      | no        |
| `cashout_source_ip_not_allowed`                | 403  | The operation's source IP is outside `cashoutSourceIps`. Integrators must pass the end user's real IP in `X-Acting-Ip`.                                                                                                                                                                                                                       | no        |
| `credential_not_found`                         | 404  | The `clientId` in the path does not exist in this tenant.                                                                                                                                                                                                                                                                                     | no        |
| `facetec_attempts_exhausted`                   | 429  | The verification used up its 3 failed attempts (or the 15 total /facetec/process calls) and is FAILED. Create a new verification.                                                                                                                                                                                                             | no        |
| `facetec_match_unavailable`                    | 422  | Face match against the requested reference (`details.referenceMatch`) is not available at the provider yet. Use `referenceMatch: none` (liveness only) or wait for availability. The API never silently downgrades to liveness-only.                                                                                                          | yes       |
| `facetec_process_in_progress`                  | 409  | Another capture of this verification is being processed. Wait for the previous response (up to 15 s) before sending another.                                                                                                                                                                                                                  | yes       |
| `facetec_sdk_not_enabled`                      | 403  | `method: facetec_sdk` is not enabled for this tenant (feature `identity_verification_facetec_sdk` off or SDK keys not configured). Contact CorpX.                                                                                                                                                                                             | no        |
| `facetec_session_expired`                      | 409  | The FaceTec session token expired (10 min). Request a new one at /facetec/session and capture again; it does not count as an attempt.                                                                                                                                                                                                         | yes       |
| `facetec_session_renewal_limited`              | 429  | Too many session token renewals: at most 1 every 5 s and 30 per verification. Request a token only when about to open the camera.                                                                                                                                                                                                             | yes       |
| `facetec_unavailable`                          | 503  | FaceTec SDK processing is temporarily unavailable at the provider. Retry shortly.                                                                                                                                                                                                                                                             | yes       |
| `hash_error`                                   | 500  | Internal failure while protecting the PIN. Retry; if it persists, contact support.                                                                                                                                                                                                                                                            | yes       |
| `identity_verification_kind_not_enabled`       | 403  | The tenant has no contracted quota for this verification kind (the kind's monthlyLimits = 0). `details.kind` names it: link_unico, link_dracma, liveness, face_match_image or face_match_cpf. Contact CorpX to enable it.                                                                                                                     | no        |
| `identity_verification_monthly_limit_exceeded` | 429  | The contracted monthly quota of this verification kind (`details.kind`: link_unico, link_dracma, liveness, face_match_image or face_match_cpf) has been used in the BRT calendar month. The default is 10 for link kinds and 0 for SDK kinds when the policy does not set monthlyLimits. Every 201 counts and failure/expiry is not refunded. | no        |
| `invalid_acting_document`                      | 400  | `X-Acting-Document` must be a CPF (11 digits) or CNPJ (14 digits).                                                                                                                                                                                                                                                                            | no        |
| `invalid_cashout_hours`                        | 422  | `cashoutHours` with an invalid `HH:MM`, `start` equal to `end`, or an unknown timezone.                                                                                                                                                                                                                                                       | no        |
| `invalid_consume_ttl`                          | 400  | `consumeTtlMinutes` must be between 1 and 60.                                                                                                                                                                                                                                                                                                 | no        |
| `invalid_display_message`                      | 400  | `displayMessage` must be one-line plain text without links/markup and at most 240 characters.                                                                                                                                                                                                                                                 | no        |
| `invalid_identity_verification_policy`         | 400  | identityVerification is tenant-scoped. monthlyLimit is an integer from 1 to 1000000; perDocumentPerHour and tenantPerMinute are integers from 1 to 1000. An absent field uses the default.                                                                                                                                                    | no        |
| `invalid_justification`                        | 400  | `justification` is required and has at most 500 characters.                                                                                                                                                                                                                                                                                   | no        |
| `invalid_method`                               | 400  | `method` must be `link` or `facetec_sdk`; `facetec_sdk` requires `provider: dracma_trust`.                                                                                                                                                                                                                                                    | no        |
| `invalid_provider`                             | 400  | `provider` must be `unico` or `dracma_trust`.                                                                                                                                                                                                                                                                                                 | no        |
| `invalid_purpose`                              | 400  | `purpose` is not in the public identity-verification enum.                                                                                                                                                                                                                                                                                    | no        |
| `invalid_reference_id`                         | 400  | `referenceId` must contain 1–128 safe ASCII characters.                                                                                                                                                                                                                                                                                       | no        |
| `invalid_reference_match`                      | 400  | `referenceMatch` must be `none`, `dracma` or `image` and only applies to `method: facetec_sdk`.                                                                                                                                                                                                                                               | no        |
| `invalid_risk`                                 | 400  | `risk.action` must be allow, challenge or deny; `risk.score`, when sent, is between 0 and 1. A deny does not block the request — the block is only stored.                                                                                                                                                                                    | no        |
| `invalid_verification_ttl`                     | 400  | Identity-verification `ttlMinutes` must be between 1 and 60.                                                                                                                                                                                                                                                                                  | no        |
| `limit_request_above_requested`                | 422  | The approved amount is above the request. Approval may be lower than or equal to the request, never higher.                                                                                                                                                                                                                                   | no        |
| `limit_request_bundle_required`                | 409  | The request belongs to a multi-operation bundle and must be decided through the bundle decision endpoint.                                                                                                                                                                                                                                     | no        |
| `limit_request_closed`                         | 409  | The request was already approved, refused or cancelled and accepts no further decision or cancellation.                                                                                                                                                                                                                                       | no        |
| `limit_request_document_type_invalid`          | 422  | `documentType` is not in this account's catalog (individual or company) and was not asked for by the reviewer.                                                                                                                                                                                                                                | no        |
| `limit_request_documents_missing`              | 422  | Submitting for review is refused when a catalog type marked required has no antivirus-approved file. The current catalog marks none. `details.missing` lists the types.                                                                                                                                                                       | no        |
| `limit_request_info_missing`                   | 422  | The reply to the information request is incomplete. `details.missing` lists the types (or `message`, when no file was requested).                                                                                                                                                                                                             | no        |
| `limit_request_not_above_current`              | 422  | The requested (or approved) amount is not above the account's current effective limit.                                                                                                                                                                                                                                                        | no        |
| `limit_request_not_found`                      | 404  | The `requestId` does not exist on this account.                                                                                                                                                                                                                                                                                               | no        |
| `limit_request_operation_unavailable`          | 422  | `operation` or `window` is not part of the limits contract (pix_out, ted_out, boleto, internal_out × single_transfer, daytime, nighttime, monthly).                                                                                                                                                                                           | no        |
| `limit_request_pending`                        | 409  | A limit increase for the same operation and window is already under review. Cancel it or wait for the decision.                                                                                                                                                                                                                               | no        |
| `limits_unavailable`                           | 503  | The limits service did not respond. Retry shortly.                                                                                                                                                                                                                                                                                            | yes       |
| `no_pending_change`                            | 404  | There is no scheduled loosening to cancel or bring forward.                                                                                                                                                                                                                                                                                   | no        |
| `pin_change_disabled`                          | 403  | Replacement without `currentPin` while hosted reset is on. A caller who knows the current PIN still changes it with PUT. Otherwise request a link with `POST /v1/people/pin/reset-request`; the operator chooses the new PIN on the CorpX page after the facial check. The first enrollment still uses PUT.                                   | no        |
| `pin_invalid`                                  | 403  | Wrong PIN. The attempt was counted.                                                                                                                                                                                                                                                                                                           | no        |
| `pin_locked`                                   | 423  | 6 wrong attempts: unlocking requires resetting the PIN.                                                                                                                                                                                                                                                                                       | no        |
| `pin_not_found`                                | 404  | No PIN registered for the given operator.                                                                                                                                                                                                                                                                                                     | no        |
| `pin_not_set`                                  | 403  | This operator has no PIN registered in this tenant.                                                                                                                                                                                                                                                                                           | no        |
| `pin_required`                                 | 428  | The credential requires `X-Acting-Document` and `X-Transaction-Pin` on cashout operations.                                                                                                                                                                                                                                                    | no        |
| `pin_reset_not_enrolled`                       | 409  | This operator has no PIN yet. The first enrollment is `PUT /v1/people/pin`. The per-account alias still accepts the same PUT.                                                                                                                                                                                                                 | no        |
| `pin_reset_rate_limited`                       | 429  | Too many PIN reset requests for this operator in the last hour. The `Retry-After` header carries the seconds.                                                                                                                                                                                                                                 | yes       |
| `pin_temporarily_locked`                       | 429  | 3 wrong attempts: locked for 15 minutes. The `Retry-After` header carries the seconds.                                                                                                                                                                                                                                                        | no        |
| `provider_error`                               | 502  | The verification provider returned an error. `partner` carries the raw detail when available. Capture again; it does not count as an attempt.                                                                                                                                                                                                 | yes       |
| `provider_session_starting`                    | 409  | The facial session is already being created. Retry the same link.                                                                                                                                                                                                                                                                             | yes       |
| `provider_session_unavailable`                 | 409  | The provider session cannot be resumed; create a new verification.                                                                                                                                                                                                                                                                            | no        |
| `provider_unavailable`                         | 503  | The identity-verification provider is unavailable or not configured.                                                                                                                                                                                                                                                                          | yes       |
| `rate_limited`                                 | 429  | The journey anti-fraud rate limit was reached. Wait for the applicable window and retry.                                                                                                                                                                                                                                                      | no        |
| `reference_already_consumed`                   | 409  | Another proof was already consumed for this tenant, purpose and referenceId.                                                                                                                                                                                                                                                                  | no        |
| `reference_image_required`                     | 400  | The verification was created with `referenceMatch: image`; send `referenceImage` (base64 JPEG/PNG) in /facetec/process.                                                                                                                                                                                                                       | no        |
| `same_actor`                                   | 422  | The person who proposes the approval cannot be the one who accepts it, except `solo: true` when the approver is admin_super.                                                                                                                                                                                                                  | no        |
| `verification_expired`                         | 410  | The verification link expired or the journey already ended.                                                                                                                                                                                                                                                                                   | no        |
| `verification_method_mismatch`                 | 409  | The route does not apply to this verification's `method`: /facetec/\* requires `facetec_sdk`; the hosted page requires `link`.                                                                                                                                                                                                                | no        |
| `verification_not_consumable`                  | 409  | The verification is not approved/fresh or is not bound to the supplied purpose and referenceId.                                                                                                                                                                                                                                               | no        |
| `verification_not_found`                       | 404  | The verification does not exist in this tenant. IDs owned by another tenant return the same 404.                                                                                                                                                                                                                                              | no        |
| `verification_not_pending`                     | 409  | The verification has already reached a terminal state.                                                                                                                                                                                                                                                                                        | no        |
| `weak_pin`                                     | 422  | PIN outside the policy (6–12 digits, no repetition, sequence, short pattern or birth date).                                                                                                                                                                                                                                                   | no        |
| `workflow_unavailable`                         | 503  | The durable identity-verification workflow could not be started.                                                                                                                                                                                                                                                                              | yes       |

## Account opening

| Code                        | HTTP | What happened and what to do                                                                                                                                                                                                                                                                                                                                                                                          | Retryable |
| --------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `administrator_required`    | 422  | Opening a company with centralized biometry requires exactly one partner with `isAdministrator: true`. That person completes the capture.                                                                                                                                                                                                                                                                             | no        |
| `biometry_not_accepted`     | 422  | This tenant does not accept a `biometry` object on account opening. Capture uses the link in `persons[].biometryLink` or `POST /v1/accreditations/{id}/capture`.                                                                                                                                                                                                                                                      | no        |
| `capture_call_limit`        | 429  | This link reached the maximum number of capture calls. Issue a new link.                                                                                                                                                                                                                                                                                                                                              | no        |
| `capture_expired`           | 410  | The capture link expired. Request another with `POST /v1/accreditations/{id}/capture` or the person retry.                                                                                                                                                                                                                                                                                                            | no        |
| `capture_failed_limit`      | 422  | Biometry was rejected too many times on this link. Issue a new link.                                                                                                                                                                                                                                                                                                                                                  | no        |
| `capture_in_progress`       | 409  | A capture call is already in progress for this link. Wait for it to finish and try again.                                                                                                                                                                                                                                                                                                                             | yes       |
| `capture_not_available`     | 409  | Capture is only available while the accreditation is `PENDING_BIOMETRY` and the verification has been opened.                                                                                                                                                                                                                                                                                                         | no        |
| `document_body_required`    | 422  | With centralized biometry, the company PDF goes in `contentBase64`. There is no upload URL.                                                                                                                                                                                                                                                                                                                           | no        |
| `document_not_accepted`     | 422  | The biometry provider refused the document: file type not accepted or verification already closed.                                                                                                                                                                                                                                                                                                                    | no        |
| `documents_incomplete`      | 409  | Approving a PJ without the required PDFs in the archive (object with size > 0). Use `forceIncompleteDocuments` + `reason` for an audited override.                                                                                                                                                                                                                                                                    | no        |
| `dracma_not_configured`     | 422  | The tenant has no active Dracma credential. Account opening with `provider=dracma` reads the verification with that credential; the CorpX global key is not a substitute.                                                                                                                                                                                                                                             | no        |
| `dracma_unavailable`        | 503  | Dracma did not respond in time. The verification was not accepted: a network failure does not approve biometrics. Try again.                                                                                                                                                                                                                                                                                          | yes       |
| `evidence_not_found`        | 422  | The `biometry.evidenceId` does not exist (or does not belong to your tenant). Only applies to external biometrics flows enabled on request; contact support.                                                                                                                                                                                                                                                          | no        |
| `feature_disabled`          | 403  | The **accreditation (BaaS)** feature is not enabled for your tenant. Contact CorpX to enable it. (Reads remain available.)                                                                                                                                                                                                                                                                                            | no        |
| `file_too_large`            | 413  | Company PDF above 50 MB.                                                                                                                                                                                                                                                                                                                                                                                              | no        |
| `invalid_callback_uri`      | 400  | The `callbackUri` you sent is not registered for your tenant, or is not accepted (only `https://` and an application scheme; no credentials in the URI, no `#`, no `localhost` or internal network address). Register it under Identity verifications in the panel when that API is enabled, or ask CorpX support. The comparison is exact. See [Returning to your app](/baas/guias/abertura-de-contas/callback-uri). | no        |
| `invalid_content_type`      | 422  | `contentType` must be `application/pdf` for company document uploads.                                                                                                                                                                                                                                                                                                                                                 | no        |
| `invalid_document`          | 400  | Document has an unexpected digit count (CPF=11, CNPJ=14).                                                                                                                                                                                                                                                                                                                                                             | no        |
| `invalid_document_type`     | 400  | Invalid `documentType` — use `CPF` or `CNPJ`.                                                                                                                                                                                                                                                                                                                                                                         | no        |
| `invalid_kind`              | 422  | Invalid company document `kind`. Accepted: `company_articles`, `company_proof_of_address`, `cnpj_card`, `financial_statements`, `business_license`, `regulatory_license`, `other`.                                                                                                                                                                                                                                    | no        |
| `invalid_status`            | 409  | Company document upload blocked for the current status (only `PENDING_BIOMETRY` / `BIOMETRY_APPROVED` / `PENDING_REVIEW`).                                                                                                                                                                                                                                                                                            | no        |
| `kyc_not_configured`        | 503  | Centralized biometry is enabled for this tenant, but neither the tenant nor CorpX has an account configured at the provider.                                                                                                                                                                                                                                                                                          | no        |
| `kyc_upstream`              | 502  | The biometry provider did not complete this step. You can try again.                                                                                                                                                                                                                                                                                                                                                  | yes       |
| `mixed_biometry_mode`       | 422  | PJ: all partners must use the same biometry mode. Dracma does not mix with the default flow or with another provider.                                                                                                                                                                                                                                                                                                 | no        |
| `not_pj`                    | 422  | Company document upload is only accepted on PJ accreditations (`POST .../documents`).                                                                                                                                                                                                                                                                                                                                 | no        |
| `presign_error`             | 500  | Failed to generate the upload link for the evidence or corporate document. Safe to retry.                                                                                                                                                                                                                                                                                                                             | no        |
| `provider_not_enabled`      | 422  | The given external biometry provider is not enabled for your tenant. Contact support.                                                                                                                                                                                                                                                                                                                                 | no        |
| `review_in_kyc_provider`    | 409  | Review of this opening happens at the biometry provider. Approving or rejecting it here does not apply.                                                                                                                                                                                                                                                                                                               | no        |
| `storage_unavailable`       | 503  | KYC archive (evidence bucket) temporarily unavailable.                                                                                                                                                                                                                                                                                                                                                                | no        |
| `too_many_files`            | 422  | More than 10 `kind=other` files on the same accreditation.                                                                                                                                                                                                                                                                                                                                                            | no        |
| `unsupported_provider`      | 422  | Unrecognized external biometry provider.                                                                                                                                                                                                                                                                                                                                                                              | no        |
| `verification_already_used` | 409  | This verification id is already bound to another account opening that has not failed. Each id approves one journey.                                                                                                                                                                                                                                                                                                   | no        |
| `verification_cpf_mismatch` | 422  | The CPF in the verification `subject.cpf` is not the person's (holder or partner), or the response had no CPF. Without the 11 digits the id identifies no one.                                                                                                                                                                                                                                                        | no        |
| `verification_not_approved` | 422  | The Dracma verification is not `approved`. `pending` and `review_required` do not open an account.                                                                                                                                                                                                                                                                                                                    | no        |
| `workflow_signal_failed`    | 502  | Failed to signal the accreditation workflow; retry.                                                                                                                                                                                                                                                                                                                                                                   | no        |

## Boleto Charge

Issuing and consulting boletos of the account itself (Boleto Charge). Distinct from Boleto Pay, which pays someone else's boleto.

| Code                                            | HTTP | What happened and what to do                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Retryable |
| ----------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `boleto_charge_account_disabled`                | 403  | Boleto issuance is not enabled for this account. boletoCharge.enabled=true on the tenant policy enables every account; on the account policy, only that account. The tenant boleto_charge feature must also be on.                                                                                                                                                                                                                                                                                      | no        |
| `boleto_charge_account_holder_not_found`        | 422  | The settlement bank does not recognize this account holder in the boleto module. This is not a missing beneficiary: the holder must exist there before registration.                                                                                                                                                                                                                                                                                                                                    | no        |
| `boleto_charge_batch_chunk_invalid`             | 400  | Each batch upload must contain between 1 and 50 boletos.                                                                                                                                                                                                                                                                                                                                                                                                                                                | no        |
| `boleto_charge_batch_empty`                     | 409  | The batch has no items to dispatch.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | no        |
| `boleto_charge_batch_item_conflict`             | 409  | The identifier already exists in the batch with another payload.                                                                                                                                                                                                                                                                                                                                                                                                                                        | no        |
| `boleto_charge_batch_item_not_found`            | 404  | Batch item not found.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | no        |
| `boleto_charge_batch_not_editable`              | 409  | Only a DRAFT batch accepts item changes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                | no        |
| `boleto_charge_batch_not_found`                 | 404  | Boleto Charge batch not found in this account.                                                                                                                                                                                                                                                                                                                                                                                                                                                          | no        |
| `boleto_charge_batch_too_large`                 | 400  | A batch accepts at most 5,000 boletos.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | no        |
| `boleto_charge_beneficiary_not_found`           | 404  | This account has no boleto beneficiary yet. Registration or the first issuance registers the holder and returns 202 boleto_charge_beneficiary_pending.                                                                                                                                                                                                                                                                                                                                                  | no        |
| `boleto_charge_beneficiary_registration_failed` | 502  | The settlement bank rejected beneficiary registration, synchronously or by webhook in the last 24 hours. The message carries the reason; on a recent rejection, `details.lastEvent` carries `rejectionCode` and `rejectionReason`, and the `Retry-After` header carries the seconds until issuance registers again on its own. Retrying issuance before that does not help: fix the account data and register again with `POST .../boleto/charge/beneficiary`, which does not wait. Nothing was issued. | no        |
| `boleto_charge_beneficiary_transition_invalid`  | 409  | The requested eligibility is not a valid transition from the current status. eligible goes to underReview or ineligible; underReview goes to eligible or ineligible; ineligible only returns to underReview.                                                                                                                                                                                                                                                                                            | no        |
| `boleto_charge_issuance_in_progress`            | 409  | An issuance is already in progress for this identifier.                                                                                                                                                                                                                                                                                                                                                                                                                                                 | yes       |
| `boleto_charge_issuance_outcome_unknown`        | 409  | The previous attempt may have reached the settlement bank, but its outcome was not confirmed. Do not retry automatically.                                                                                                                                                                                                                                                                                                                                                                               | no        |
| `boleto_charge_monthly_limit_exceeded`          | 429  | The issuance does not fit the tenant or account remaining monthly quota. Reservation is atomic and no batch item was started.                                                                                                                                                                                                                                                                                                                                                                           | no        |
| `commercial_policy_staff_required`              | 403  | Boleto Charge and identity-verification commercial quotas can only be changed by CorpX staff.                                                                                                                                                                                                                                                                                                                                                                                                           | no        |
| `invalid_batch_item`                            | 422  | A batch item violates issuance rules; the message identifies its index.                                                                                                                                                                                                                                                                                                                                                                                                                                 | no        |
| `invalid_boleto_charge_policy`                  | 400  | boletoCharge.enabled must be a boolean and boletoCharge.maxIssuesPerMonth, when present, an integer from 1 to 1000000. Unlimited mode is not supported.                                                                                                                                                                                                                                                                                                                                                 | no        |
| `quota_unavailable`                             | 503  | The monthly quota could not be read or reserved right now.                                                                                                                                                                                                                                                                                                                                                                                                                                              | yes       |

## Balance holds

Hold part of the balance, release it to another CorpX account, or cancel it.

| Code                             | HTTP | What happened and what to do                                                                                                                                           | Retryable |
| -------------------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `account_locked_for_holds`       | 403  | The account has an active outflow lock (block, hours or source IP), and it applies to holding and releasing balance. Cancelling a hold is still allowed.               | no        |
| `hold_managed_by_order`          | 409  | This hold belongs to a P2P order. Only the order releases or cancels it; use the order routes.                                                                         | no        |
| `hold_not_active`                | 409  | The hold is not `active`: it was already released, cancelled, or is being released under another `Idempotency-Key`. Read the hold to see its state.                    | no        |
| `hold_not_found`                 | 404  | There is no hold with this `holdId` on this account.                                                                                                                   | no        |
| `insufficient_available_balance` | 422  | The account's available balance is lower than the hold amount. Nothing was held. Check `availableAmount` on `GET /balance`.                                            | no        |
| `release_exceeds_hold`           | 422  | `amount` plus `fee.amount` must equal the total hold amount. Partial release does not exist: cancel and create another hold.                                           | no        |
| `release_failed`                 | 422  | The release transfer was refused and the amount is held again (`active`). `details.cause` carries the reason. Fix it and release again with another `Idempotency-Key`. | no        |

## P2P Crypto

P2P stablecoin market: profiles, wallets, ads, orders, signing and disputes.

| Code                             | HTTP | What happened and what to do                                                                                                                                                                                                                                                                                             | Retryable |
| -------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- |
| `ad_closed`                      | 409  | The ad was closed and cannot be edited again. Create another one.                                                                                                                                                                                                                                                        | no        |
| `ad_not_found`                   | 404  | There is no ad with this `adId` in the market.                                                                                                                                                                                                                                                                           | no        |
| `ad_suspended`                   | 422  | The ad was suspended by CorpX and only CorpX can reactivate it. It can be edited or closed, but not turned back on.                                                                                                                                                                                                      | no        |
| `ad_unavailable`                 | 409  | The ad does not accept orders right now: it is paused, has no stock for the amount, has no quote, its pair is disabled, its advertiser is not approved, its wallet is not cleared, or the advertiser's tenant left the market. Nothing was locked. List the market again.                                                | no        |
| `advertiser_not_approved`        | 403  | Only an approved advertiser creates or reactivates ads. Request approval with `POST /p2p/advertiser-requests`.                                                                                                                                                                                                           | no        |
| `advertiser_request_not_allowed` | 409  | An advertiser request is already under review, or the account is already an advertiser, or it was suspended.                                                                                                                                                                                                             | no        |
| `amount_above_cap`               | 422  | The amount exceeds a cap: per order (the lowest among the market's and the two parties' tenants'), the advertiser's per-order cap, or the buyer's daily cap (day in Brasília time). The message says which.                                                                                                              | no        |
| `amount_out_of_ad_limits`        | 422  | The order amount is outside the ad's minimum and maximum. The message carries the accepted range.                                                                                                                                                                                                                        | no        |
| `contact_already_verified`       | 409  | This P2P profile channel is already confirmed.                                                                                                                                                                                                                                                                           | no        |
| `contact_code_invalid`           | 422  | The contact confirmation code is invalid or expired.                                                                                                                                                                                                                                                                     | no        |
| `contact_code_locked`            | 422  | Too many code attempts. Request a new code.                                                                                                                                                                                                                                                                              | no        |
| `contact_code_rate_limited`      | 429  | Too many codes sent for this contact. Wait before requesting another.                                                                                                                                                                                                                                                    | no        |
| `contact_delivery_failed`        | 503  | The confirmation code could not be sent right now. Try resending.                                                                                                                                                                                                                                                        | no        |
| `contract_not_available`         | 409  | This party's signed copy does not exist yet: signing has not finished or is disabled in the market.                                                                                                                                                                                                                      | no        |
| `delivery_deadline_out_of_range` | 422  | `deliveryDeadlineMin` is outside the market's range. The message carries the range.                                                                                                                                                                                                                                      | no        |
| `dispute_already_decided`        | 409  | The dispute was already decided; it no longer accepts messages or evidence.                                                                                                                                                                                                                                              | no        |
| `dispute_already_open`           | 409  | A dispute is already open on this order.                                                                                                                                                                                                                                                                                 | no        |
| `dispute_not_allowed_yet`        | 409  | A dispute is not allowed yet: the buyer disputes after the delivery deadline; the seller, 60 minutes after sending or 24 hours after on-chain confirmation.                                                                                                                                                              | no        |
| `dispute_not_found`              | 404  | This order has no dispute.                                                                                                                                                                                                                                                                                               | no        |
| `hold_lock_unknown`              | 503  | The bank did not confirm the balance lock. The order was not opened and CorpX reconciles the balance; do not repeat the order before checking the balance.                                                                                                                                                               | no        |
| `holder_only`                    | 403  | Only the account holder performs this operation. The document in `X-Acting-Document` belongs to someone else.                                                                                                                                                                                                            | no        |
| `holds_unavailable`              | 503  | The balance hold service is unavailable. The order was not opened.                                                                                                                                                                                                                                                       | no        |
| `invalid_network`                | 422  | The wallet network is not accepted. Check the networks on `GET /p2p/pairs`.                                                                                                                                                                                                                                              | no        |
| `invalid_offset`                 | 422  | `offset` must stay within 5% of the current Binance spot (the same cap as 500 bps). The message carries the limit in BRL, with 4 decimal places.                                                                                                                                                                         | no        |
| `invalid_spread`                 | 422  | `spreadBps` must be between -500 and 500.                                                                                                                                                                                                                                                                                | no        |
| `invalid_username`               | 422  | `username` accepts 3 to 24 characters: lowercase letters, digits, `_` and `.`.                                                                                                                                                                                                                                           | no        |
| `invalid_wallet_address`         | 422  | The address is not valid for the given network.                                                                                                                                                                                                                                                                          | no        |
| `order_not_cancellable`          | 409  | The order can no longer be cancelled: both parties signed the contract or it has ended.                                                                                                                                                                                                                                  | no        |
| `order_not_concluded`            | 409  | The receipt is only issued once the trade is concluded: released, signed by both parties, seller paid and fee charged.                                                                                                                                                                                                   | no        |
| `order_not_found`                | 404  | There is no order with this `orderId` in which this account is a party.                                                                                                                                                                                                                                                  | no        |
| `order_role_not_allowed`         | 403  | This step belongs to the other party: the seller reports the txid and the buyer releases the amount.                                                                                                                                                                                                                     | no        |
| `order_step_out_of_order`        | 409  | The order is not at the step this call requires. Read the order to see its `status`.                                                                                                                                                                                                                                     | no        |
| `order_unavailable`              | 503  | The order could not be opened due to a temporary failure. Nothing stayed locked; retry with another `Idempotency-Key`.                                                                                                                                                                                                   | no        |
| `p2p_contact_unverified`         | 422  | The P2P profile e-mail or phone is not confirmed yet. Confirm both before advertising or trading.                                                                                                                                                                                                                        | no        |
| `pair_not_enabled`               | 422  | The pair (crypto and network) is not enabled in the market.                                                                                                                                                                                                                                                              | no        |
| `price_evidence_not_found`       | 404  | The order exists but has no recorded quote evidence. Only happens for orders opened before evidence recording was introduced.                                                                                                                                                                                            | no        |
| `price_unavailable`              | 409  | Binance did not return the spot price at opening time (timeout, HTTP error, rate limit or invalid response). Opening requires this lookup, even for fixed-price ads, because the quote at that moment is recorded as evidence. No order was created and nothing was locked. Retry shortly with the same Idempotency-Key. | no        |
| `profile_not_found`              | 404  | There is no public P2P profile with this `username`.                                                                                                                                                                                                                                                                     | no        |
| `screening_unavailable`          | 503  | Wallet risk screening is unavailable. The order was not opened; retry shortly.                                                                                                                                                                                                                                           | no        |
| `self_trade`                     | 409  | The account tried to trade against its own ad or against an ad from another account of the same holder.                                                                                                                                                                                                                  | no        |
| `signer_contact_missing`         | 422  | The P2P profile does not have a confirmed e-mail and phone to sign the contract. The order was not opened; confirm the contact on the P2P profile before trading.                                                                                                                                                        | no        |
| `stock_below_reserved`           | 422  | Stock cannot go below what is already reserved in open orders.                                                                                                                                                                                                                                                           | no        |
| `term_not_available`             | 409  | The consolidation term does not exist yet: the trade has not concluded or the PDF has not been generated.                                                                                                                                                                                                                | no        |
| `txid_already_used`              | 409  | This txid was already reported on another order.                                                                                                                                                                                                                                                                         | no        |
| `txid_invalid_format`            | 422  | The txid does not match the pair's network format (Tron: 64 hexadecimal characters).                                                                                                                                                                                                                                     | no        |
| `txid_limit_reached`             | 422  | The order already received the maximum number of txids. Open a dispute if the transfer does not show up.                                                                                                                                                                                                                 | no        |
| `username_change_too_soon`       | 409  | The `username` was already changed in the last 90 days. Creating the profile does not count; each change starts a 90-day cooldown. `details.nextChangeAt` carries the date from which a change is accepted again.                                                                                                        | no        |
| `username_required`              | 409  | Set the P2P profile `username` before requesting to advertise.                                                                                                                                                                                                                                                           | no        |
| `username_taken`                 | 409  | Another profile in the market already uses this `username`. The `username` is unique across every tenant.                                                                                                                                                                                                                | no        |
| `wallet_already_registered`      | 409  | This wallet is already registered on this account.                                                                                                                                                                                                                                                                       | no        |
| `wallet_in_open_order`           | 409  | The wallet is in an ongoing order or is the wallet of an active ad. Wait for the order to finish or change the ad's wallet.                                                                                                                                                                                              | no        |
| `wallet_not_approved`            | 422  | The wallet did not pass risk screening or is still under review. On order opening, `details.walletOf` says whose wallet was refused (`taker` or `maker`).                                                                                                                                                                | no        |
| `wallet_not_found`               | 404  | There is no wallet with this `walletId` on this account.                                                                                                                                                                                                                                                                 | no        |