> This page is for BaaS.

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

# Erros

Toda resposta de erro tem o mesmo corpo. Decida pelo `errorCode`, nunca pelo
`message` — o texto é apresentação e pode mudar; o código é contrato.

```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" }
}
```

| Campo       | O que é                                                                            |
| ----------- | ---------------------------------------------------------------------------------- |
| `errorCode` | Código estável. A lista abaixo é gerada do código-fonte do gateway a cada release. |
| `message`   | Explicação em português, para log e suporte. Não faça parsing.                     |
| `docs`      | Link para a âncora do código nesta página.                                         |
| `requestId` | Id da requisição no gateway. Cite ao abrir chamado.                                |
| `partner`   | Só quando a falha veio do liquidante: o erro cru dele, para diagnóstico.           |

> **Enum aberto**
>
> Novos códigos podem surgir sem mudança de versão. Trate um `errorCode`
> desconhecido como erro genérico do mesmo status HTTP: 4xx é problema na
> requisição (não repita sem mudar algo), 5xx e `retryable: sim` podem ser
> repetidos com a mesma `Idempotency-Key`.

## Gerais

Autenticação, headers, formato e disponibilidade. Podem acontecer em qualquer rota.

| Código                                 | HTTP | O que aconteceu e o que fazer                                                                                                                                                                                                                                                                                                                | Retentativa |
| -------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `account_blocked`                      | 423  | A conta foi bloqueada operacionalmente pela CorpX. Consultas e entradas continuam disponíveis, mas saídas financeiras são recusadas até o desbloqueio.                                                                                                                                                                                       | não         |
| `account_has_balance`                  | 422  | `POST /v1/accounts/{accountId}/close` no caminho exclusivo: o liquidante ainda tem saldo disponível (`available` ≠ 0, ou `total` ≠ 0 sem bloqueio). Retire o saldo antes. O corpo traz o saldo cru do liquidante.                                                                                                                            | não         |
| `account_has_locked_balance`           | 422  | `POST /v1/accounts/{accountId}/close` no caminho exclusivo: o saldo disponível está zerado, mas há saldo bloqueado no liquidante (`locked` ≠ 0, por exemplo retenção de MED). A conta só é encerrada depois que o bloqueio é liberado. O corpo traz o saldo cru do liquidante.                                                               | não         |
| `account_has_pix_keys`                 | 422  | `POST /v1/accounts/{accountId}/close` no caminho exclusivo: a conta ainda tem chave PIX no liquidante. Exclua as chaves antes. O corpo traz só o tipo de cada chave, não o valor.                                                                                                                                                            | não         |
| `account_holder_missing`               | 404  | O liquidante não devolveu o cadastro do titular desta conta.                                                                                                                                                                                                                                                                                 | não         |
| `account_not_found`                    | 404  | O `accountId` do path não existe.                                                                                                                                                                                                                                                                                                            | não         |
| `acting_not_holder`                    | 403  | X-Acting-Document não é o documento do titular da conta.                                                                                                                                                                                                                                                                                     | não         |
| `bank_not_found`                       | 404  | `GET /v1/banks/{code}` não achou COMPE nem ISPB no catálogo (ou a linha está desabilitada).                                                                                                                                                                                                                                                  | não         |
| `banking_unavailable`                  | 503  | O provedor bancário não está disponível para esta operação neste momento. Repita em alguns segundos; nada foi executado.                                                                                                                                                                                                                     | sim         |
| `beneficiary_check_unavailable`        | 503  | Não foi possível confirmar o destino da transferência interna por documento. Retente ou use `/transfers/internal/by-bank-account`.                                                                                                                                                                                                           | não         |
| `cognito_error`                        | 502  | Falha no provedor de identidade ao criar ou alterar a credencial. Repita; se persistir, acione o suporte.                                                                                                                                                                                                                                    | sim         |
| `cognito_unavailable`                  | 503  | Provedor de identidade indisponível. Repita em instantes.                                                                                                                                                                                                                                                                                    | sim         |
| `credential_revoked`                   | 403  | A credencial usada foi revogada. Gere uma nova credencial no internet banking (IB) ou com a CorpX (BaaS).                                                                                                                                                                                                                                    | não         |
| `db_error`                             | 500  | Erro interno de persistência.                                                                                                                                                                                                                                                                                                                | não         |
| `db_unavailable`                       | 503  | Banco de dados do gateway indisponível. Nada foi executado; repita em instantes.                                                                                                                                                                                                                                                             | sim         |
| `evidence_not_approved`                | 422  | A evidência de biometria (`biometry.evidenceId`) ainda não passou pela verificação de conteúdo, ou foi recusada. Envie uma nova evidência.                                                                                                                                                                                                   | não         |
| `forbidden`                            | 403  | Você não tem permissão para realizar esta ação no recurso solicitado.                                                                                                                                                                                                                                                                        | não         |
| `holder_not_pj`                        | 422  | Pedido de atualização cadastral é só de conta PJ. PF usa PUT /holder/address.                                                                                                                                                                                                                                                                | não         |
| `holder_update_closed`                 | 409  | O pedido não está no estado que aceita esta ação.                                                                                                                                                                                                                                                                                            | não         |
| `holder_update_document_type_invalid`  | 422  | documentType não faz parte deste pedido.                                                                                                                                                                                                                                                                                                     | não         |
| `holder_update_documents_missing`      | 422  | Falta documento obrigatório com scanStatus APPROVED.                                                                                                                                                                                                                                                                                         | não         |
| `holder_update_kind_invalid`           | 422  | kind deve ser address ou registration.                                                                                                                                                                                                                                                                                                       | não         |
| `holder_update_not_found`              | 404  | Pedido de atualização não encontrado nesta conta.                                                                                                                                                                                                                                                                                            | não         |
| `holder_update_pending`                | 409  | Já existe um pedido aberto do mesmo tipo nesta conta.                                                                                                                                                                                                                                                                                        | não         |
| `holder_update_required`               | 422  | Conta PJ não altera endereço direto. Abra um pedido em POST /v1/accounts/\{accountId}/holder-updates com comprovante.                                                                                                                                                                                                                        | não         |
| `idempotency_conflict`                 | 409  | A `Idempotency-Key` já foi usada por outro tenant em um endpoint que deriva identificadores dela (fluxos habilitados sob demanda). Reenviar uma `Idempotency-Key` com corpo diferente **não** devolve conflito nos demais endpoints: você recebe o resultado da operação original. Ver [Idempotência](/baas/guias/comece-aqui/idempotencia). | não         |
| `identity_not_approved`                | 409  | A verificação de identidade da jornada de consent ainda não foi aprovada. A jornada permanece pendente; o titular refaz a captura pelo mesmo link.                                                                                                                                                                                           | não         |
| `identity_stale`                       | 409  | A verificação de identidade expirou. A jornada permanece pendente; o titular refaz a captura pelo mesmo link.                                                                                                                                                                                                                                | não         |
| `ingest_unavailable`                   | 503  | Componente interno de ingestão indisponível. Repita em instantes.                                                                                                                                                                                                                                                                            | sim         |
| `init_error`                           | 500  | Falha ao inicializar dependências do gateway. Repita; se persistir, acione o suporte com o `requestId`.                                                                                                                                                                                                                                      | sim         |
| `insufficient_scope`                   | 403  | A credencial não tem o **escopo** necessário para a rota (ex.: `qrcode.manage`, `pix_out.create`), ou é somente leitura tentando uma escrita. A mensagem nomeia o escopo que falta. Veja o [Guia de Autenticação](/baas/guias/autenticacao/oauth2).                                                                                          | não         |
| `integrator_credential_required`       | 403  | A rota movimenta dinheiro e exige credencial de integrador (`client_credentials`) emitida pela CorpX. Token de sessão de usuário do Portal é recusado mesmo quando o usuário tem acesso à conta.                                                                                                                                             | não         |
| `internal_error`                       | 500  | Ocorreu um erro inesperado em nossos servidores.                                                                                                                                                                                                                                                                                             | não         |
| `invalid_account`                      | 400  | `accountId` informado para a credencial não é um UUID ou não pertence ao tenant.                                                                                                                                                                                                                                                             | não         |
| `invalid_body`                         | 400  | O corpo não é um JSON válido.                                                                                                                                                                                                                                                                                                                | não         |
| `invalid_client`                       | 400  | `clientId` mal formado.                                                                                                                                                                                                                                                                                                                      | não         |
| `invalid_path`                         | 400  | Um segmento do path está vazio ou mal formado (por exemplo `transactionId` ausente na timeline).                                                                                                                                                                                                                                             | não         |
| `invalid_scope`                        | 400  | Um dos escopos pedidos para a credencial não existe. Veja a lista em Autenticação.                                                                                                                                                                                                                                                           | não         |
| `invalid_state`                        | 409  | A operação não se aplica ao estado atual do recurso.                                                                                                                                                                                                                                                                                         | não         |
| `marshal_error`                        | 500  | Falha interna ao serializar a resposta. Repita; se persistir, acione o suporte com o `requestId`.                                                                                                                                                                                                                                            | sim         |
| `med_request_closed`                   | 409  | A contestação não está no estado que aceita esta ação.                                                                                                                                                                                                                                                                                       | não         |
| `med_request_info_missing`             | 422  | Reenviar depois de um pedido de informação exige mensagem ou anexo aprovado.                                                                                                                                                                                                                                                                 | não         |
| `med_request_not_found`                | 404  | Contestação não encontrada nesta conta.                                                                                                                                                                                                                                                                                                      | não         |
| `med_request_not_outgoing_pix`         | 422  | Só um PIX enviado por esta conta pode ser contestado.                                                                                                                                                                                                                                                                                        | não         |
| `med_request_out_of_window`            | 422  | O PIX passou da janela de 80 dias para contestação.                                                                                                                                                                                                                                                                                          | não         |
| `med_request_pending`                  | 409  | Já existe contestação aberta para este endToEndId.                                                                                                                                                                                                                                                                                           | não         |
| `method_not_allowed`                   | 405  | O método HTTP não é aceito nesta rota. Confira o método na referência da API.                                                                                                                                                                                                                                                                | não         |
| `missing_idempotency_key`              | 400  | O header Idempotency-Key é obrigatório.                                                                                                                                                                                                                                                                                                      | não         |
| `missing_tenant`                       | 400  | O header `X-Tenant-Id` é obrigatório e não foi informado.                                                                                                                                                                                                                                                                                    | não         |
| `no_accounts`                          | 404  | O tenant ainda não tem nenhuma conta. Conclua a abertura de conta antes de operar.                                                                                                                                                                                                                                                           | não         |
| `payload_too_large`                    | 413  | Corpo da requisição acima do limite da rota (evidência de MED: 10 MB). Reduza o arquivo ou use a URL de upload.                                                                                                                                                                                                                              | não         |
| `pix_transaction_not_found`            | 404  | O endToEndId não é um PIX desta conta.                                                                                                                                                                                                                                                                                                       | não         |
| `rate_check_unavailable`               | 503  | Não foi possível validar o limite de jornadas agora. Retente em instantes.                                                                                                                                                                                                                                                                   | não         |
| `request_in_progress`                  | 409  | A mesma `Idempotency-Key` já está em processamento neste tenant. Aguarde e consulte de novo; não é um segundo encerramento.                                                                                                                                                                                                                  | sim         |
| `scope_not_self_service`               | 403  | Esse escopo só pode ser concedido pela CorpX, não pela própria credencial.                                                                                                                                                                                                                                                                   | não         |
| `storage_error`                        | 502  | Falha ao gravar ou ler o arquivo de evidência. Repita; se persistir, acione o suporte.                                                                                                                                                                                                                                                       | sim         |
| `temporal_unavailable`                 | 503  | O orquestrador de operações assíncronas não respondeu; a operação não foi iniciada. Repita com a mesma `Idempotency-Key`.                                                                                                                                                                                                                    | sim         |
| `tenant_disabled`                      | 403  | O tenant está desativado: nenhuma rota da API responde. Fale com o suporte CorpX para reativar o acesso.                                                                                                                                                                                                                                     | não         |
| `tenant_forbidden`                     | 403  | O token não está autorizado para o tenant do `X-Tenant-Id`. Vale para qualquer rota `/v1/`: a credencial e o header precisam apontar para o mesmo tenant.                                                                                                                                                                                    | não         |
| `tenant_mismatch`                      | 403  | O `X-Tenant-Id` não corresponde ao tenant da conta no path (ou ao `tenantId` do body).                                                                                                                                                                                                                                                       | não         |
| `tenant_suspended`                     | 403  | Há uma pendência em aberto e as operações de **escrita** estão suspensas. Consultas seguem funcionando. Fale com o suporte CorpX para regularizar.                                                                                                                                                                                           | não         |
| `unauthorized`                         | 401  | Header `Authorization` ausente. **Token inválido ou expirado retorna `403`** (obtenha um novo token via `client_credentials`).                                                                                                                                                                                                               | não         |
| `unsupported_media_type`               | 422  | Tipo de arquivo não aceito para evidência de MED. Envie PDF, PNG ou JPEG.                                                                                                                                                                                                                                                                    | não         |
| `user_token_forbidden_on_financial_op` | 403  | Token de usuário não movimenta dinheiro: operações financeiras exigem credencial de aplicação (`client_credentials`).                                                                                                                                                                                                                        | não         |
| `workflow_start_failed`                | 500  | Não foi possível iniciar a operação assíncrona. Repita com a mesma `Idempotency-Key`; se persistir, acione o suporte.                                                                                                                                                                                                                        | sim         |
| `workflow_timeout`                     | 504  | A operação não concluiu dentro da janela síncrona. O resultado é indeterminado: consulte o extrato ou o status antes de repetir.                                                                                                                                                                                                             | não         |

## Liquidante

Recusas do banco liquidante traduzidas para código estável. O bloco `partner` traz o original.

| Código                                            | HTTP | O que aconteceu e o que fazer                                                                                                                                                                                                                                                                                         | Retentativa |
| ------------------------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `account_not_entitled`                            | 409  | O credenciamento da conta está concluído, mas o liquidante não habilitou este serviço para ela — outras operações da mesma conta seguem funcionando. Não é falha transitória nem erro do seu pedido: repetir a chamada não resolve enquanto o liquidante não fizer a habilitação. Acione o suporte com o `accountId`. | não         |
| `account_not_ready`                               | 409  | A conta ainda não tem contrapartida no liquidante — credenciamento em andamento, recusado ou nunca concluído. Não é indisponibilidade da API: nenhuma operação bancária funciona nessa conta até a accreditation chegar a `ACTIVE`.                                                                                   | não         |
| `already_at_partner`                              | 409  | CPF/CNPJ já credenciado no liquidante por outro participante. Requer transferência de controle via suporte.                                                                                                                                                                                                           | não         |
| `automatic_pix_contract_blocked`                  | 409  | O arranjo bloqueia o mesmo contrato nas últimas 24 horas, solicitação aguardando autorização para o mesmo contrato e pagador, e proposta idêntica recusada ou cancelada há menos de 30 dias. Aguarde a resposta do pagador ou use outro número de contrato.                                                           | não         |
| `automatic_pix_date_out_of_window`                | 422  | O vencimento do agendamento precisa estar no ciclo vigente e com pelo menos 2 dias de antecedência; a retentativa precisa ser posterior ao vencimento original, dentro de 7 dias corridos e do mesmo ciclo. Consulte as datas sugeridas antes de pedir retentativa.                                                   | não         |
| `automatic_pix_identifier_in_use`                 | 409  | O identifier do QR Code composto já foi usado nesta conta. Cada QR composto precisa de um identifier próprio.                                                                                                                                                                                                         | não         |
| `automatic_pix_payer_bank_unavailable`            | 422  | O ISPB informado não existe ou não está ativo no Pix Automático. Confira o banco do pagador.                                                                                                                                                                                                                          | não         |
| `automatic_pix_receiver_ineligible`               | 422  | O recebedor do Pix Automático precisa ser pessoa jurídica ativa com dados bancários completos no liquidante.                                                                                                                                                                                                          | não         |
| `automatic_pix_recurrence_not_authorized`         | 409  | Agendamentos, postergações e retentativas só valem para recorrência com status authorized.                                                                                                                                                                                                                            | não         |
| `automatic_pix_retry_not_allowed`                 | 409  | Retentativa exige paymentRetry=true na recorrência, liquidação não concluída, nenhuma tentativa em andamento no mesmo dia e datas ainda não usadas, até o limite de 3.                                                                                                                                                | não         |
| `automatic_pix_scheduling_conflict`               | 409  | Cada ciclo aceita um agendamento ativo. Postergar só vale enquanto o agendamento está created.                                                                                                                                                                                                                        | não         |
| `automatic_pix_value_above_payer_limit`           | 422  | Em recorrência de valor variável, cada cobrança respeita o maximumValue da proposta e o payerMaximumValue definido pelo pagador na autorização.                                                                                                                                                                       | não         |
| `automatic_pix_value_mismatch`                    | 422  | Recorrência de valor fixo cobra exatamente value; a de valor variável exige value no agendamento. Na criação, value e maximumValue são mutuamente exclusivos.                                                                                                                                                         | não         |
| `bacen_rejected_content`                          | 400  | Conteúdo textual (descrição/mensagem) com caractere não aceito pelo BACEN.                                                                                                                                                                                                                                            | não         |
| `balance_reservation_failed`                      | 422  | Falha na reserva de saldo (saldo bloqueado, em liquidação ou concorrência com outra operação).                                                                                                                                                                                                                        | não         |
| `boleto_already_settled`                          | 409  | Boleto já baixado/pago. Consulte o pagamento original antes de reenviar.                                                                                                                                                                                                                                              | não         |
| `boleto_amount_mismatch`                          | 422  | Valor divergente do registrado no boleto (considere juros, multa e desconto).                                                                                                                                                                                                                                         | não         |
| `boleto_charge_barcode_active`                    | 409  | O liquidante recusou porque o barcode ainda está ativo.                                                                                                                                                                                                                                                               | não         |
| `boleto_charge_beneficiary_ineligible`            | 422  | O liquidante devolveu o beneficiário como inapto ou em análise. Não há o que repetir até a situação mudar.                                                                                                                                                                                                            | não         |
| `boleto_charge_discount_invalid`                  | 422  | limitDate do desconto ausente, ilegível ou não anterior a dueDate.                                                                                                                                                                                                                                                    | não         |
| `boleto_charge_identifier_in_use`                 | 409  | O liquidante recusou a emissão porque o identifier já está ativo para o beneficiário.                                                                                                                                                                                                                                 | não         |
| `boleto_charge_not_eligible_for_write_off_cancel` | 409  | Cancelar baixa exige status writtenOff com baixa no arranjo. Não cancela boleto em aberto.                                                                                                                                                                                                                            | não         |
| `boleto_charge_reductions_exceed_amount`          | 422  | A soma das reduções não pode zerar o título.                                                                                                                                                                                                                                                                          | não         |
| `boleto_charge_rules_inconsistent`                | 422  | Encargo incompatível com o calculationModel, ou min/max de pagamento inconsistente.                                                                                                                                                                                                                                   | não         |
| `boleto_scheduled`                                | 409  | Existe agendamento ativo para o mesmo código de barras.                                                                                                                                                                                                                                                               | não         |
| `challenge_failure`                               | 422  | Falha de PIN/2FA na operação junto ao liquidante.                                                                                                                                                                                                                                                                     | não         |
| `conflict`                                        | 409  | Conflito de estado no liquidante (ex.: recurso já processado).                                                                                                                                                                                                                                                        | não         |
| `identifier_conflict`                             | 409  | Identificador (`Identifier`) já usado no liquidante. Reenviar com o mesmo valor não cria uma nova operação.                                                                                                                                                                                                           | não         |
| `insufficient_funds`                              | 422  | Saldo insuficiente apurado pelo liquidante no momento da liquidação.                                                                                                                                                                                                                                                  | não         |
| `invalid_field`                                   | 400  | Validação de campo específico no liquidante. `partner.field` indica o campo e a mensagem traz o limite quando informado.                                                                                                                                                                                              | não         |
| `invalid_payload`                                 | 400  | O liquidante recusou o corpo da requisição. O bloco `partner` traz a validação original.                                                                                                                                                                                                                              | não         |
| `invalid_pix_key`                                 | 400  | Formato da chave incompatível com o tipo (`CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`).                                                                                                                                                                                                                                    | não         |
| `key_inactive`                                    | 422  | Chave existe mas está inativa/em portabilidade. Use outra chave ou dados bancários.                                                                                                                                                                                                                                   | não         |
| `key_not_found`                                   | 404  | Chave inexistente no DICT. Confira a digitação ou peça outra chave ao destinatário.                                                                                                                                                                                                                                   | não         |
| `key_ownership_mismatch`                          | 422  | Tentativa de registrar/usar chave cujo documento não é o do titular da conta.                                                                                                                                                                                                                                         | não         |
| `limit_exceeded`                                  | 422  | Limite estourado sem discriminação de janela (o liquidante não informou qual).                                                                                                                                                                                                                                        | não         |
| `limit_exceeded_daily`                            | 422  | No PIX, limite da janela diurna (06:00–20:00). Na transferência interna, limite do dia calendário (São Paulo 00:00–23:59). A mensagem traz o restante quando disponível.                                                                                                                                              | não         |
| `limit_exceeded_monthly`                          | 422  | Limite mensal acumulado. Só libera na virada do mês ou com aumento de limite.                                                                                                                                                                                                                                         | não         |
| `limit_exceeded_nightly`                          | 422  | Limite da janela noturna (20:00–06:00), normalmente menor que o diurno.                                                                                                                                                                                                                                               | não         |
| `limit_exceeded_transaction`                      | 422  | Limite por transação. Divida a operação ou solicite aumento de limite.                                                                                                                                                                                                                                                | não         |
| `not_found`                                       | 404  | Recurso inexistente no liquidante (id, chave ou transação).                                                                                                                                                                                                                                                           | não         |
| `not_supported`                                   | 501  | A rota existe no contrato, mas o liquidante não expõe a operação. Repetir não resolve — é ausência de capacidade, não indisponibilidade.                                                                                                                                                                              | não         |
| `partial_refund_not_supported`                    | 400  | Legado — não é mais retornado: estorno parcial passou a ser aceito. Um valor acima do original devolve `refund_amount_exceeded`.                                                                                                                                                                                      | não         |
| `partner_account_disabled`                        | 422  | Conta de origem desabilitada no liquidante (precisa de reativação).                                                                                                                                                                                                                                                   | não         |
| `partner_error`                                   | 502  | Falha não classificada na comunicação com o liquidante. Pode ser repetida.                                                                                                                                                                                                                                            | sim         |
| `partner_forbidden`                               | 502  | Operação bloqueada pelo liquidante para a conta (produto ou permissão não habilitados).                                                                                                                                                                                                                               | não         |
| `partner_internal`                                | 502  | Erro interno (5xx) do liquidante. Pode ser repetida.                                                                                                                                                                                                                                                                  | sim         |
| `partner_rate_limited`                            | 429  | Throttling do liquidante sobre o tráfego da CorpX. Nada no seu pedido está errado — reduza a cadência e repita com backoff.                                                                                                                                                                                           | sim         |
| `partner_rejected`                                | 422  | Recusa do liquidante por política interna, risco ou antifraude. O bloco `partner` traz o motivo informado.                                                                                                                                                                                                            | não         |
| `partner_unauthorized`                            | 502  | Credencial da CorpX junto ao liquidante recusada. Não é problema da sua credencial; aguarde alguns minutos antes de reenviar.                                                                                                                                                                                         | não         |
| `partner_unavailable`                             | 502  | Indisponibilidade ou falha de gateway do liquidante. Pode ser repetida.                                                                                                                                                                                                                                               | sim         |
| `payer_key_required`                              | 422  | A conta pagadora precisa ter ao menos uma chave PIX ativa para enviar. O problema é da conta de origem, não da chave do destinatário: cadastre uma chave (a aleatória serve) e repita.                                                                                                                                | não         |
| `pix_key_limit_exceeded`                          | 422  | Limite de quantidade de chaves por conta (5 para PF, 20 para PJ).                                                                                                                                                                                                                                                     | não         |
| `qr_amount_mismatch`                              | 422  | QR Code com valor fixo não aceita valor diferente do original.                                                                                                                                                                                                                                                        | não         |
| `qr_gone`                                         | 409  | QR Code removido ou expirado no liquidante.                                                                                                                                                                                                                                                                           | não         |
| `recipient_account_not_found`                     | 422  | Banco/agência/conta de destino inexistente. Aplica-se a TED e transferência interna.                                                                                                                                                                                                                                  | não         |
| `refund_amount_exceeded`                          | 400  | Valor de estorno maior que o saldo estornável do PIX original.                                                                                                                                                                                                                                                        | não         |
| `timeout`                                         | 504  | Timeout na chamada ao liquidante. A operação pode ter sido criada — consulte antes de reenviar.                                                                                                                                                                                                                       | sim         |

## PIX out

| Código                                                                                | HTTP | O que aconteceu e o que fazer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Retentativa |
| ------------------------------------------------------------------------------------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `batch_not_found`                                                                     | 404  | BigPix: o `batchId` consultado não existe.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | não         |
| `batch_too_large`                                                                     | 400  | BigPix: o valor pedido geraria mais de 99 parcelas.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | não         |
| `beneficiary_incomplete`                                                              | 422  | O beneficiário cadastrado não tem todos os dados necessários para a operação escolhida.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | não         |
| `beneficiary_not_active_at_partner`                                                   | 422  | O beneficiário existe no cadastro mas ainda não está ativo no liquidante.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | não         |
| `beneficiary_not_found`                                                               | 404  | O beneficiário informado não existe no cadastro da conta.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | não         |
| `dict_lookup_limit_exceeded`                                                          | 429  | Os limites de consulta DICT foram atingidos: uma contagem absoluta (`maxLookupsPerDay`, `maxLookupsPerMinute`, `maxNotFoundPer5min`) ou uma taxa por janela de tempo (consultas por transferência, ou fração de consultas que não resolvem chave, de 5 min a 30 dias). Valem os da policy do tenant/conta e, para os campos não preenchidos, o default global — sempre contados **por conta**, nunca somados no tenant. A mensagem indica qual contador ou janela disparou. Aguarde a janela renovar (00:00 BRT para o limite diário; janela deslizante para as taxas) ou ajuste os limites no Backoffice. Consumo abusivo é acompanhado e tem consequências — ver [Consultas de chave PIX](/baas/guias/pagar/consulta-dict). | não         |
| `invalid_amount`                                                                      | 400  | `amount` ausente, não positivo ou com mais de duas casas decimais.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | não         |
| `invalid_bank_code`                                                                   | 400  | No PIX por dados bancários, `bankCode` aceita o Compe de 3 dígitos ou o ISPB de 8 dígitos. Em TED só o Compe é aceito — ver [TED](#ted).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | não         |
| `invalid_identifier`                                                                  | 400  | O `identifier` excede o tamanho aceito, usa caracteres não permitidos, ou — no pedido de aumento de limite — não é idêntico ao header `Idempotency-Key`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | não         |
| `invalid_pix_batch_policy`                                                            | 400  | pixBatch.maxItems deve ser inteiro entre 1 e 5000 e pixBatch.enabled deve ser booleano.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | não         |
| `pix_batch_account_disabled`                                                          | 403  | PIX em lote não está habilitado nesta conta. pixBatch.enabled=true na policy do tenant libera todas as contas; na policy da conta, só ela. Ajuste feito pela CorpX.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | não         |
| \<a id="pix_batch_acknowledgement_required">\</a>`pix_batch_acknowledgement_required` | 409  | O dispatch precisa de \{"acknowledged": true} confirmando que o resumo da conferência (valores, saldo e limites) foi lido.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | não         |
| `pix_batch_chunk_invalid`                                                             | 400  | Cada PUT de itens deve conter entre 1 e 50 pagamentos válidos; o corpo lista as linhas rejeitadas em errors\[] e nada foi salvo.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | não         |
| `pix_batch_csv_invalid`                                                               | 400  | O CSV não segue o modelo (cabeçalho, separador ou linhas inválidas) ou excede 5 MiB (413). errors\[] aponta linha e campo; nada foi salvo.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | não         |
| `pix_batch_empty`                                                                     | 409  | O lote não tem itens para conferir ou disparar.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | não         |
| `pix_batch_has_invalid_items`                                                         | 409  | A conferência marcou itens inválidos (chave inexistente, identifier já usado, acima do limite por operação…). Baixe o CSV de correção em GET .../items/export?status=invalid, corrija ou remova e confira de novo.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | não         |
| `pix_batch_insufficient_balance`                                                      | 422  | O saldo disponível no momento do dispatch é menor que o total do lote. Nenhum item foi iniciado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | não         |
| `pix_batch_item_conflict`                                                             | 409  | O identifier já existe no lote com outro conteúdo. Repetir o mesmo identifier com o mesmo conteúdo é aceito sem efeito.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | não         |
| `pix_batch_item_not_found`                                                            | 404  | Item do lote de PIX não encontrado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | não         |
| `pix_batch_limit_exceeded`                                                            | 422  | A conferência mostrou que o total do lote passa de um limite de saída da conta (review\.limits com sufficient=false). Sem esta recusa os primeiros PIX sairiam e os seguintes falhariam por limite. Remova itens ou aguarde a janela do limite e confira de novo. Nenhum item foi iniciado.                                                                                                                                                                                                                                                                                                                                                                                                                                   | não         |
| `pix_batch_no_receipts`                                                               | 409  | Comprovantes só existem para lotes encerrados (COMPLETED, PARTIAL_FAILED ou FAILED) com ao menos um item liquidado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | não         |
| `pix_batch_not_editable`                                                              | 409  | Só lotes DRAFT ou REVIEWED aceitam alteração de itens ou nova conferência. Depois do dispatch o lote é imutável.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | não         |
| `pix_batch_not_found`                                                                 | 404  | Lote de PIX não encontrado nesta conta.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | não         |
| `pix_batch_not_reviewed`                                                              | 409  | O dispatch exige um lote REVIEWED com todos os itens conferidos. Chame POST .../review e aguarde o status.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | não         |
| `pix_batch_receipt_unavailable`                                                       | 409  | O item ainda não liquidou (ou falhou); só itens COMPLETED têm comprovante.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | não         |
| `pix_batch_too_large`                                                                 | 400  | O lote ultrapassa o máximo de itens da conta (pixBatch.maxItems; padrão 50, teto 5.000). A mensagem traz o limite efetivo e sua origem.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | não         |
| `policy_denied`                                                                       | 422  | Uma regra de política configurada para a conta ou tenant recusou a operação — transferência, criação de QR Code, criação de chave PIX ou estorno. O corpo traz `violations` com `rule` e `message` de cada regra violada. Ver [Políticas e Regras](/baas/guias/autenticacao/politicas).                                                                                                                                                                                                                                                                                                                                                                                                                                       | não         |
| `receipt_render_failed`                                                               | 500  | Falha ao gerar o PDF do comprovante. Tente novamente; o pagamento em si não é afetado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | sim         |

## QR Code

| Código          | HTTP | O que aconteceu e o que fazer                                             | Retentativa |
| --------------- | ---- | ------------------------------------------------------------------------- | ----------- |
| `missing_field` | 400  | `pixKey` ausente — e, no QR dinâmico, `value` ausente ou não positivo.    | não         |
| `missing_param` | 400  | Consulta e cancelamento exigem o query param `identifier` (alias `txid`). | não         |

## Chaves PIX

| Código                             | HTTP | O que aconteceu e o que fazer                                                                                                                        | Retentativa |
| ---------------------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `key_type_temporarily_unavailable` | 422  | Cadastro de chave `email` ou `phone` está temporariamente indisponível. Use `cpf`, `cnpj` ou `random`. Listar e apagar chaves desses tipos continua. | não         |

## Devolução

| Código                           | HTTP | O que aconteceu e o que fazer                                                                                                                                                  | Retentativa |
| -------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| `med_info_missing`               | 422  | O esclarecimento não pode ser concluído sem mensagem nem anexo novo desde o pedido da análise.                                                                                 | não         |
| `med_lock_unavailable`           | 409  | A retenção de saldo não pôde ser feita ou desfeita: já há valor retido, a disputa está encerrada ou o liquidante recusou a operação.                                           | não         |
| `med_not_found`                  | 404  | A disputa (MED) não existe ou não pertence a esta conta.                                                                                                                       | não         |
| `med_not_writable`               | 409  | A disputa não aceita mensagem nem anexo neste momento: só em `awaiting_defense` (antes da resposta) ou em `info_requested`.                                                    | não         |
| `med_opened_by_us`               | 409  | A MED foi aberta pela CorpX em nome do cliente (`direction: opened`): não há defesa, mensagem, anexo nem decisão. Acompanhe `partnerStatus` e `lastUpdatedAt` até o resultado. | não         |
| `med_refund_amount_invalid`      | 422  | O valor da devolução é obrigatório, positivo e não pode passar do que falta devolver (`remaining`).                                                                            | não         |
| `med_refund_in_progress`         | 409  | Há uma devolução desta disputa ainda em liquidação; aguarde a conclusão antes da próxima etapa.                                                                                | não         |
| `med_refund_not_completed`       | 409  | A conta só é liberada depois que a devolução da rodada estiver concluída e o restante retido.                                                                                  | não         |
| `med_review_not_pending`         | 409  | A ação exige a disputa em análise (`pending_review`) ou com esclarecimento pendente (`info_requested`); ela já avançou.                                                        | não         |
| `med_step_out_of_order`          | 409  | A etapa pedida não é a próxima da rodada, ou a disputa não está em execução. As etapas de devolução são executadas uma por vez, na ordem.                                      | não         |
| `original_transaction_not_found` | 404  | A transação original (`originalEndToEnd`) não foi encontrada.                                                                                                                  | não         |

## TED

| Código                 | HTTP | O que aconteceu e o que fazer                                                                  | Retentativa |
| ---------------------- | ---- | ---------------------------------------------------------------------------------------------- | ----------- |
| `invalid_account_type` | 400  | `accountType` deve ser `CHECKING`, `SAVINGS`, `PAYMENT` ou `SALARY`. Omitido, vale `CHECKING`. | não         |
| `invalid_tax_number`   | 400  | `taxNumber` deve ter 11 (CPF) ou 14 (CNPJ) dígitos.                                            | não         |
| `missing_fields`       | 400  | Falta `value`, `holderName`, `branch` ou `account`.                                            | não         |

## Transferência interna

| Código                          | HTTP | O que aconteceu e o que fazer                                                                                                                                                                                   | Retentativa |
| ------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `multiple_destination_accounts` | 409  | Em `/transfers/internal/by-document`, o documento tem mais de uma conta ativa. Enderece pela conta: `/transfers/internal/by-bank-account` (agência + número) ou `/transfers/internal` (`destinationAccountId`). | não         |

## Extrato, lançamentos e exportações

| Código                        | HTTP | O que aconteceu e o que fazer                                                                                                     | Retentativa |
| ----------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `bucket_mismatch`             | 409  | O arquivo do export foi gerado em outro ambiente e não pode ser baixado por aqui. Gere o export novamente.                        | não         |
| `date_range_too_wide`         | 400  | A janela do extrato passa de 31 dias. Quebre em períodos menores.                                                                 | não         |
| `invalid_cursor`              | 400  | O `cursor` de paginação é inválido ou pertence a outra consulta. Recomece sem `cursor`.                                           | não         |
| `invalid_date_range`          | 400  | `startDate` / `endDate` fora do formato `YYYY-MM-DD`.                                                                             | não         |
| `invalid_filter`              | 400  | Filtro do extrato avançado inválido (`type`, `direction`, `status`, `minAmount`/`maxAmount` ou datas). A mensagem indica o campo. | não         |
| `invalid_format`              | 400  | `format` da exportação deve ser `csv`, `pdf` ou `xlsx`.                                                                           | não         |
| `invalid_operation`           | 400  | O detalhe do lançamento exige o query param `operation`: `PIX`, `TED`, `BOLETO`, `INTERNAL` ou `FEE`.                             | não         |
| `invalid_query`               | 400  | A timeline por conta exige exatamente um entre `endToEndId` e `identifier` — nunca os dois, nunca nenhum.                         | não         |
| `invalid_s3_key`              | 500  | Referência interna do arquivo de export inválida. Gere o export novamente; se persistir, acione o suporte.                        | sim         |
| `missing_account_id`          | 400  | `accountId` ausente no path. Use `GET /v1/accounts/{accountId}/pix/payments/lookup?identifier=...`.                               | não         |
| `missing_identifier`          | 400  | Informe `identifier` ou `endToEnd` na query para localizar o pagamento.                                                           | não         |
| `not_ready`                   | 409  | O download foi pedido antes de a exportação ficar pronta. Consulte o status até `completed`.                                      | não         |
| `presign_failed`              | 500  | Falha ao gerar o link de download do arquivo já pronto. Pode ser repetido.                                                        | não         |
| `statement_rules_unavailable` | 503  | As regras de apresentação do extrato ainda não carregaram. Saldo e valor não mudam; só o texto. Repita em instantes.              | sim         |

## Webhooks

| Código                        | HTTP | O que aconteceu e o que fazer                                                                                                                                                | Retentativa |
| ----------------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `account_id_required`         | 422  | A credencial está restrita a contas específicas: informe `accountId` na subscription. Ver [Assinatura por conta](/baas/guias/conta/webhooks#assinatura-por-conta-accountid). | não         |
| `hookdeck_list_failed`        | 502  | O serviço de entregas não conseguiu listar as tentativas. Repita em instantes.                                                                                               | sim         |
| `hookdeck_retry_failed`       | 502  | O serviço de entregas recusou o reenvio. Repita em instantes.                                                                                                                | sim         |
| `hookdeck_source_unavailable` | 503  | Fonte de entregas do tenant indisponível no serviço de webhooks. Repita em instantes.                                                                                        | sim         |
| `hookdeck_sync_failed`        | 502  | Falha ao registrar o destino no nosso entregador de webhooks. Pode ser repetido.                                                                                             | não         |
| `hookdeck_unavailable`        | 503  | Serviço de entregas de webhook indisponível. Repita em instantes.                                                                                                            | sim         |
| `invalid_url`                 | 400  | A `url` precisa usar `https://`.                                                                                                                                             | não         |
| `missing_delivery_id`         | 400  | `deliveryId` ausente no path.                                                                                                                                                | não         |
| `missing_subscription_id`     | 400  | `subscriptionId` ausente no path.                                                                                                                                            | não         |
| `no_hookdeck_destination`     | 410  | A subscription não tem mais destino de entrega ativo. Recrie a subscription.                                                                                                 | não         |
| `no_hookdeck_event_found`     | 410  | A entrega saiu da janela de retenção e não pode mais ser reenviada.                                                                                                          | não         |
| `reemit_failed`               | 500  | Falha ao reemitir o evento. Repita; se persistir, acione o suporte com o `deliveryId`.                                                                                       | sim         |
| `replay_already_running`      | 409  | Já existe um replay em andamento para esta subscription. Aguarde a conclusão.                                                                                                | não         |
| `unsupported_auth_type`       | 400  | `authType` da subscription fora dos valores aceitos (`NONE`, `HMAC`, `BASIC`, `BEARER`).                                                                                     | não         |

## Assinatura de requisição (host assinado)

| Código                       | HTTP | O que aconteceu e o que fazer                                                                                                                                             | Retentativa |                           |     |
| ---------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------- | --- |
| `body_hash_mismatch`         | 400  | O corpo recebido não corresponde ao `X-Content-SHA256` assinado.                                                                                                          | não         |                           |     |
| `credential_not_yet_active`  | 403  | Credencial recém-emitida ainda na carência. Espere o `activeFrom` devolvido na emissão.                                                                                   | não         |                           |     |
| `invalid_ip`                 | 400  | Endereço ou CIDR inválido na allowlist de IPs. Use IPv4/IPv6 ou notação CIDR (`203.0.113.10/32`).                                                                         | não         |                           |     |
| `invalid_public_key`         | 422  | O PEM não é uma chave pública EC P-256 ou RSA ≥ 2048. PEM de chave **privada** é recusado com mensagem própria.                                                           | não         |                           |     |
| `ip_allowlist_derived`       | 409  | O tenant tem credenciais delegadas: a allowlist de IP dele é calculada a partir delas e não aceita edição manual.                                                         | não         |                           |     |
| `ip_allowlist_required`      | 422  | `allowedIps` ausente, vazio, com mais de 20 entradas, contendo `0.0.0.0/0` ou prefixo mais largo que `/24`.                                                               | não         |                           |     |
| `ip_not_allowed`             | 403  | A requisição saiu de um IP fora da allowlist da credencial.                                                                                                               | não         |                           |     |
| `last_public_key`            | 409  | Não é possível aposentar a última chave utilizável da credencial.                                                                                                         | não         |                           |     |
| `public_key_limit_reached`   | 409  | Limite de chaves públicas por credencial atingido. Aposente uma antes de cadastrar outra.                                                                                 | não         |                           |     |
| `public_key_required`        | 422  | A emissão de credencial delegada exige `publicKeyPem`.                                                                                                                    | não         |                           |     |
| `request_signature_invalid`  | 403  | A assinatura não confere com a chave anunciada no `kid`. Compare a string canônica em `POST /v1/security/signature/verify`; confira também que a assinatura ES256 é \`R\\ | \\          | S\` (64 bytes) e não DER. | não |
| `request_signature_required` | 403  | Falta `X-Request-Signature`, `X-Request-Timestamp` ou `X-Content-SHA256`.                                                                                                 | não         |                           |     |
| `request_timestamp_skew`     | 403  | `X-Request-Timestamp` fora da janela de 300s. Sincronize o relógio do servidor (NTP).                                                                                     | não         |                           |     |
| `scope_not_delegable`        | 403  | O escopo pedido para a credencial filha não está entre os da credencial que está delegando, ou não é delegável.                                                           | não         |                           |     |
| `signature_required`         | 403  | A requisição chegou em `client.api.corpx.com` sem os headers de assinatura. É bloqueio de borda, antes do token.                                                          | não         |                           |     |
| `signed_host_required`       | 403  | Credencial delegada usada em `tenant.api.corpx.com`. Repita em `client.api.corpx.com`, assinando.                                                                         | não         |                           |     |
| `unknown_kid`                | 403  | O `kid` não está entre as chaves ativas da credencial: foi aposentado, ou ainda está na carência de 18h.                                                                  | não         |                           |     |

## Segurança da conta (travas, PIN e limites)

| Código                                         | HTTP | O que aconteceu e o que fazer                                                                                                                                                                                                                                                                                                      | Retentativa |
| ---------------------------------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `acting_document_required`                     | 400  | Envie `X-Acting-Document` (CPF do operador) junto com o PIN.                                                                                                                                                                                                                                                                       | não         |
| `cashout_locked`                               | 423  | O titular bloqueou a saída de dinheiro desta conta (`cashoutBlocked`).                                                                                                                                                                                                                                                             | não         |
| `cashout_outside_hours`                        | 403  | Fora da janela de horário configurada pelo titular. A mensagem traz a janela.                                                                                                                                                                                                                                                      | não         |
| `cashout_source_ip_not_allowed`                | 403  | O IP de origem da operação está fora de `cashoutSourceIps`. Integrador deve informar o IP real do usuário em `X-Acting-Ip`.                                                                                                                                                                                                        | não         |
| `credential_not_found`                         | 404  | O `clientId` do path não existe neste tenant.                                                                                                                                                                                                                                                                                      | não         |
| `facetec_attempts_exhausted`                   | 429  | A verificação esgotou as 3 tentativas reprovadas (ou as 15 chamadas totais a /facetec/process) e ficou FAILED. Crie uma nova verificação.                                                                                                                                                                                          | não         |
| `facetec_match_unavailable`                    | 422  | A comparação facial com a referência pedida (`details.referenceMatch`) ainda não está disponível no provedor. Use `referenceMatch: none` (só prova de vida) ou aguarde a disponibilidade. A API nunca rebaixa para só-vida em silêncio.                                                                                            | sim         |
| `facetec_process_in_progress`                  | 409  | Outra captura desta verificação está sendo processada. Aguarde a resposta anterior (até 15 s) antes de enviar outra.                                                                                                                                                                                                               | sim         |
| `facetec_sdk_not_enabled`                      | 403  | `method: facetec_sdk` não está habilitado para o tenant (feature `identity_verification_facetec_sdk` desligada ou chaves do SDK não cadastradas). Fale com a CorpX.                                                                                                                                                                | não         |
| `facetec_session_expired`                      | 409  | O session token do FaceTec venceu (10 min). Peça outro em /facetec/session e refaça a captura; não conta tentativa.                                                                                                                                                                                                                | sim         |
| `facetec_session_renewal_limited`              | 429  | Renovações de session token em excesso: no máximo 1 a cada 5 s e 30 por verificação. Peça o token só quando for abrir a câmera.                                                                                                                                                                                                    | sim         |
| `facetec_unavailable`                          | 503  | O processamento do FaceTec SDK está temporariamente indisponível no provedor. Tente de novo em instantes.                                                                                                                                                                                                                          | sim         |
| `hash_error`                                   | 500  | Falha interna ao proteger o PIN. Repita; se persistir, acione o suporte.                                                                                                                                                                                                                                                           | sim         |
| `identity_verification_kind_not_enabled`       | 403  | O tenant não tem cota contratada para este tipo de verificação (monthlyLimits do tipo = 0). `details.kind` diz qual: link_unico, link_dracma, liveness, face_match_image ou face_match_cpf. Fale com a CorpX para habilitar.                                                                                                       | não         |
| `identity_verification_monthly_limit_exceeded` | 429  | A cota mensal contratada do tipo de verificação (`details.kind`: link_unico, link_dracma, liveness, face_match_image ou face_match_cpf) foi consumida no mês civil (BRT). O padrão é 10 para os tipos por link e 0 para os do SDK quando a policy não define monthlyLimits. Cada resposta 201 conta e falha/expiração não estorna. | não         |
| `invalid_acting_document`                      | 400  | `X-Acting-Document` deve ser um CPF (11 dígitos) ou CNPJ (14 dígitos).                                                                                                                                                                                                                                                             | não         |
| `invalid_cashout_hours`                        | 422  | `cashoutHours` com `HH:MM` inválido, `start` igual a `end`, ou timezone desconhecido.                                                                                                                                                                                                                                              | não         |
| `invalid_consume_ttl`                          | 400  | `consumeTtlMinutes` deve estar entre 1 e 60.                                                                                                                                                                                                                                                                                       | não         |
| `invalid_display_message`                      | 400  | `displayMessage` deve ser texto simples, em uma linha, sem links/markup e com até 240 caracteres.                                                                                                                                                                                                                                  | não         |
| `invalid_identity_verification_policy`         | 400  | identityVerification vale só para o tenant. monthlyLimit é inteiro de 1 a 1000000; perDocumentPerHour e tenantPerMinute são inteiros de 1 a 1000. Campo ausente usa o padrão.                                                                                                                                                      | não         |
| `invalid_justification`                        | 400  | `justification` é obrigatória e tem no máximo 500 caracteres.                                                                                                                                                                                                                                                                      | não         |
| `invalid_method`                               | 400  | `method` deve ser `link` ou `facetec_sdk`; `facetec_sdk` exige `provider: dracma_trust`.                                                                                                                                                                                                                                           | não         |
| `invalid_provider`                             | 400  | `provider` deve ser `unico` ou `dracma_trust`.                                                                                                                                                                                                                                                                                     | não         |
| `invalid_purpose`                              | 400  | `purpose` não pertence ao enum público de verificação de identidade.                                                                                                                                                                                                                                                               | não         |
| `invalid_reference_id`                         | 400  | `referenceId` deve ter 1–128 caracteres ASCII seguros.                                                                                                                                                                                                                                                                             | não         |
| `invalid_reference_match`                      | 400  | `referenceMatch` deve ser `none`, `dracma` ou `image` e só se aplica a `method: facetec_sdk`.                                                                                                                                                                                                                                      | não         |
| `invalid_risk`                                 | 400  | `risk.action` deve ser allow, challenge ou deny; `risk.score`, quando enviado, fica entre 0 e 1. Um `deny` não impede o pedido — o bloco só é armazenado.                                                                                                                                                                          | não         |
| `invalid_verification_ttl`                     | 400  | `ttlMinutes` da verificação deve estar entre 1 e 60.                                                                                                                                                                                                                                                                               | não         |
| `limit_request_above_requested`                | 422  | O valor aprovado é maior que o pedido. A aprovação pode ser menor ou igual ao pedido, nunca maior.                                                                                                                                                                                                                                 | não         |
| `limit_request_bundle_required`                | 409  | O pedido pertence a um lote com várias operações e deve ser decidido pela rota de decisão do lote.                                                                                                                                                                                                                                 | não         |
| `limit_request_closed`                         | 409  | O pedido já foi aprovado, recusado ou cancelado e não aceita nova decisão nem cancelamento.                                                                                                                                                                                                                                        | não         |
| `limit_request_document_type_invalid`          | 422  | `documentType` não faz parte do catálogo da conta (PF ou PJ) nem foi pedido pelo analista.                                                                                                                                                                                                                                         | não         |
| `limit_request_documents_missing`              | 422  | O envio para análise recusa quando falta arquivo aprovado de um tipo marcado como obrigatório no catálogo. O catálogo atual não marca nenhum. `details.missing` lista os tipos.                                                                                                                                                    | não         |
| `limit_request_info_missing`                   | 422  | A resposta ao pedido de informações está incompleta. `details.missing` lista os tipos (ou `message`, quando não foi pedido arquivo).                                                                                                                                                                                               | não         |
| `limit_request_not_above_current`              | 422  | O valor pedido (ou aprovado) não é maior que o limite efetivo atual da conta.                                                                                                                                                                                                                                                      | não         |
| `limit_request_not_found`                      | 404  | O `requestId` não existe nesta conta.                                                                                                                                                                                                                                                                                              | não         |
| `limit_request_operation_unavailable`          | 422  | `operation` ou `window` não faz parte do contrato de limites (pix_out, ted_out, boleto, internal_out × single_transfer, daytime, nighttime, monthly).                                                                                                                                                                              | não         |
| `limit_request_pending`                        | 409  | Já existe um pedido de aumento em análise para a mesma operação e janela. Cancele o pedido aberto ou espere a decisão.                                                                                                                                                                                                             | não         |
| `limits_unavailable`                           | 503  | O serviço de limites não respondeu. Repita em instantes.                                                                                                                                                                                                                                                                           | sim         |
| `no_pending_change`                            | 404  | Não há afrouxamento agendado para cancelar ou antecipar.                                                                                                                                                                                                                                                                           | não         |
| `pin_change_disabled`                          | 403  | Substituição sem `currentPin` enquanto o reset hospedado está ativo. Quem sabe o PIN atual troca no PUT. Sem ele, peça um link em `POST /v1/people/pin/reset-request`; o operador escolhe o PIN novo na página da CorpX, depois da prova facial. O primeiro cadastro continua no PUT.                                              | não         |
| `pin_invalid`                                  | 403  | PIN incorreto. A tentativa foi contada.                                                                                                                                                                                                                                                                                            | não         |
| `pin_locked`                                   | 423  | 6 tentativas incorretas: a liberação exige redefinir o PIN.                                                                                                                                                                                                                                                                        | não         |
| `pin_not_found`                                | 404  | Não há PIN cadastrado para o operador informado.                                                                                                                                                                                                                                                                                   | não         |
| `pin_not_set`                                  | 403  | Este operador não tem PIN cadastrado neste tenant.                                                                                                                                                                                                                                                                                 | não         |
| `pin_required`                                 | 428  | A credencial exige `X-Acting-Document` e `X-Transaction-Pin` nas operações de saída.                                                                                                                                                                                                                                               | não         |
| `pin_reset_not_enrolled`                       | 409  | Este operador ainda não tem PIN. O primeiro cadastro é `PUT /v1/people/pin`. O alias por conta continua aceitando o mesmo PUT.                                                                                                                                                                                                     | não         |
| `pin_reset_rate_limited`                       | 429  | Muitos pedidos de redefinição de PIN para este operador na última hora. O header `Retry-After` traz os segundos.                                                                                                                                                                                                                   | sim         |
| `pin_temporarily_locked`                       | 429  | 3 tentativas incorretas: bloqueio de 15 minutos. O header `Retry-After` traz os segundos.                                                                                                                                                                                                                                          | não         |
| `provider_error`                               | 502  | O provedor de verificação respondeu com erro. `partner` traz o detalhe cru quando houver. Repita a captura; não conta tentativa.                                                                                                                                                                                                   | sim         |
| `provider_session_starting`                    | 409  | A sessão facial já está sendo criada. Retente o mesmo link.                                                                                                                                                                                                                                                                        | sim         |
| `provider_session_unavailable`                 | 409  | A sessão do provedor não pode ser retomada; abra uma nova verificação.                                                                                                                                                                                                                                                             | não         |
| `provider_unavailable`                         | 503  | O provedor de verificação de identidade está indisponível ou não configurado.                                                                                                                                                                                                                                                      | sim         |
| `rate_limited`                                 | 429  | O limite antifraude da jornada foi atingido. Aguarde a janela indicada e tente novamente.                                                                                                                                                                                                                                          | não         |
| `reference_already_consumed`                   | 409  | Outra prova já foi consumida para este tenant, purpose e referenceId.                                                                                                                                                                                                                                                              | não         |
| `reference_image_required`                     | 400  | A verificação foi criada com `referenceMatch: image`; envie `referenceImage` (base64 JPEG/PNG) em /facetec/process.                                                                                                                                                                                                                | não         |
| `same_actor`                                   | 422  | Quem propõe a aprovação não pode ser quem aceita, salvo `solo: true` quando o aprovador é admin_super.                                                                                                                                                                                                                             | não         |
| `verification_expired`                         | 410  | O link de verificação expirou ou a jornada já terminou.                                                                                                                                                                                                                                                                            | não         |
| `verification_method_mismatch`                 | 409  | A rota não se aplica ao `method` desta verificação: /facetec/\* exige `facetec_sdk`; a página hospedada exige `link`.                                                                                                                                                                                                              | não         |
| `verification_not_consumable`                  | 409  | A verificação não está aprovada/fresca ou não pertence ao purpose e referenceId enviados.                                                                                                                                                                                                                                          | não         |
| `verification_not_found`                       | 404  | A verificação não existe neste tenant. IDs de outro tenant produzem o mesmo 404.                                                                                                                                                                                                                                                   | não         |
| `verification_not_pending`                     | 409  | A verificação já chegou a um estado terminal.                                                                                                                                                                                                                                                                                      | não         |
| `weak_pin`                                     | 422  | PIN fora da política (6–12 dígitos, sem repetição, sequência, padrão curto ou data de nascimento).                                                                                                                                                                                                                                 | não         |
| `workflow_unavailable`                         | 503  | Não foi possível iniciar o processamento durável da verificação.                                                                                                                                                                                                                                                                   | sim         |

## Abertura de contas

| Código                      | HTTP | O que aconteceu e o que fazer                                                                                                                                                                                                                                                                                                                                                                                                          | Retentativa |
| --------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `administrator_required`    | 422  | A abertura de PJ com biometria centralizada exige exatamente um sócio com `isAdministrator: true`. É essa pessoa que faz a captura.                                                                                                                                                                                                                                                                                                    | não         |
| `biometry_not_accepted`     | 422  | Este tenant não aceita o objeto `biometry` na abertura. A captura é feita pelo link devolvido em `persons[].biometryLink` ou por `POST /v1/accreditations/{id}/capture`.                                                                                                                                                                                                                                                               | não         |
| `capture_call_limit`        | 429  | Este link atingiu o número máximo de chamadas de captura. Emita um link novo.                                                                                                                                                                                                                                                                                                                                                          | não         |
| `capture_expired`           | 410  | O link de captura venceu. Peça outro com `POST /v1/accreditations/{id}/capture` ou com o retry da pessoa.                                                                                                                                                                                                                                                                                                                              | não         |
| `capture_failed_limit`      | 422  | A biometria foi recusada vezes demais neste link. Emita um link novo.                                                                                                                                                                                                                                                                                                                                                                  | não         |
| `capture_in_progress`       | 409  | Já existe uma chamada de captura em andamento para este link. Espere ela terminar e tente de novo.                                                                                                                                                                                                                                                                                                                                     | sim         |
| `capture_not_available`     | 409  | A captura só existe enquanto o credenciamento está em `PENDING_BIOMETRY` e a verificação já foi aberta.                                                                                                                                                                                                                                                                                                                                | não         |
| `document_body_required`    | 422  | Com biometria centralizada, o PDF societário vai no campo `contentBase64`. Não há URL de upload.                                                                                                                                                                                                                                                                                                                                       | não         |
| `document_not_accepted`     | 422  | O provedor de biometria recusou o documento: tipo de arquivo não aceito ou verificação já encerrada.                                                                                                                                                                                                                                                                                                                                   | não         |
| `documents_incomplete`      | 409  | Aprovar PJ sem os PDFs obrigatórios no arquivo (objeto com tamanho > 0). Use `forceIncompleteDocuments` + `reason` para override auditado.                                                                                                                                                                                                                                                                                             | não         |
| `dracma_not_configured`     | 422  | O tenant não tem credencial Dracma ativa. A abertura com `provider=dracma` consulta a verificação nessa credencial; a chave global da CorpX não substitui.                                                                                                                                                                                                                                                                             | não         |
| `dracma_unavailable`        | 503  | A Dracma não respondeu a tempo. A verificação não foi aceita: falha de rede não aprova biometria. Tente de novo.                                                                                                                                                                                                                                                                                                                       | sim         |
| `evidence_not_found`        | 422  | O `biometry.evidenceId` não existe (ou não pertence ao seu tenant). Só se aplica a fluxos de biometria externa habilitados sob demanda; fale com o suporte.                                                                                                                                                                                                                                                                            | não         |
| `feature_disabled`          | 403  | O recurso de **credenciamento (BaaS)** não está habilitado para o seu tenant. Fale com a CorpX para habilitar. (Consultas continuam livres.)                                                                                                                                                                                                                                                                                           | não         |
| `file_too_large`            | 413  | PDF societário acima de 50 MB.                                                                                                                                                                                                                                                                                                                                                                                                         | não         |
| `invalid_callback_uri`      | 400  | O `callbackUri` enviado não está cadastrado para o seu tenant, ou não é aceito (só `https://` e esquema de aplicativo; sem credencial na URI, sem `#`, sem `localhost` nem endereço de rede interna). Cadastre a URI em Verificações de identidade no painel, quando essa API estiver habilitada, ou peça o cadastro ao suporte da CorpX. A comparação é exata. Ver [Retorno ao seu app](/baas/guias/abertura-de-contas/callback-uri). | não         |
| `invalid_content_type`      | 422  | `contentType` deve ser `application/pdf` no upload de documentos societários.                                                                                                                                                                                                                                                                                                                                                          | não         |
| `invalid_document`          | 400  | Documento com contagem de dígitos inesperada (CPF=11, CNPJ=14).                                                                                                                                                                                                                                                                                                                                                                        | não         |
| `invalid_document_type`     | 400  | `documentType` inválido — use `CPF` ou `CNPJ`.                                                                                                                                                                                                                                                                                                                                                                                         | não         |
| `invalid_kind`              | 422  | `kind` de documento societário inválido. Aceitos: `company_articles`, `company_proof_of_address`, `cnpj_card`, `financial_statements`, `business_license`, `regulatory_license`, `other`.                                                                                                                                                                                                                                              | não         |
| `invalid_status`            | 409  | Upload de documentos societários bloqueado no status atual (só `PENDING_BIOMETRY` / `BIOMETRY_APPROVED` / `PENDING_REVIEW`).                                                                                                                                                                                                                                                                                                           | não         |
| `kyc_not_configured`        | 503  | A abertura com biometria centralizada está ligada neste tenant, mas nem o tenant nem a CorpX têm conta configurada no provedor.                                                                                                                                                                                                                                                                                                        | não         |
| `kyc_upstream`              | 502  | O provedor de biometria não concluiu esta etapa. Pode tentar de novo.                                                                                                                                                                                                                                                                                                                                                                  | sim         |
| `mixed_biometry_mode`       | 422  | PJ: todos os sócios devem usar o mesmo modo de biometria. Dracma não mistura com o fluxo padrão nem com outro provedor.                                                                                                                                                                                                                                                                                                                | não         |
| `not_pj`                    | 422  | Upload de documentos societários só é aceito em accreditation PJ (`POST .../documents`).                                                                                                                                                                                                                                                                                                                                               | não         |
| `presign_error`             | 500  | Falha ao gerar o link de upload da evidência ou do documento societário. Pode ser repetido.                                                                                                                                                                                                                                                                                                                                            | não         |
| `provider_not_enabled`      | 422  | O provedor de biometria externo informado não está habilitado para o seu tenant. Fale com o suporte.                                                                                                                                                                                                                                                                                                                                   | não         |
| `review_in_kyc_provider`    | 409  | A revisão desta abertura acontece no provedor de biometria. Aprovar ou recusar por aqui não se aplica.                                                                                                                                                                                                                                                                                                                                 | não         |
| `storage_unavailable`       | 503  | Arquivo KYC (bucket de evidências) indisponível no momento.                                                                                                                                                                                                                                                                                                                                                                            | não         |
| `too_many_files`            | 422  | Mais de 10 arquivos `kind=other` na mesma accreditation.                                                                                                                                                                                                                                                                                                                                                                               | não         |
| `unsupported_provider`      | 422  | Provedor de biometria externo não reconhecido.                                                                                                                                                                                                                                                                                                                                                                                         | não         |
| `verification_already_used` | 409  | Esse id de verificação já está preso a outra abertura que não falhou. Cada id aprova uma jornada.                                                                                                                                                                                                                                                                                                                                      | não         |
| `verification_cpf_mismatch` | 422  | O CPF em `subject.cpf` da verificação não é o da pessoa (titular ou sócio), ou a resposta não trouxe CPF. Sem os 11 dígitos o id não identifica ninguém.                                                                                                                                                                                                                                                                               | não         |
| `verification_not_approved` | 422  | A verificação Dracma não está `approved`. `pending` e `review_required` não abrem conta.                                                                                                                                                                                                                                                                                                                                               | não         |
| `workflow_signal_failed`    | 502  | Falha ao sinalizar o fluxo de credenciamento; tente novamente.                                                                                                                                                                                                                                                                                                                                                                         | não         |

## Boleto Charge

Emissão e consulta de boletos da própria conta (Boleto Charge). Distinto de Boleto Pay, que paga um boleto de terceiro.

| Código                                          | HTTP | O que aconteceu e o que fazer                                                                                                                                                                                                                                                                                                                                                                                                                                         | Retentativa |
| ----------------------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `boleto_charge_account_disabled`                | 403  | Emissão de boletos não está habilitada nesta conta. boletoCharge.enabled=true na policy do tenant libera todas as contas; na policy da conta, só ela. A flag boleto_charge do tenant também precisa estar ligada.                                                                                                                                                                                                                                                     | não         |
| `boleto_charge_account_holder_not_found`        | 422  | O liquidante não reconhece o titular desta conta no módulo de boletos. Não é ausência de beneficiário: o cadastro do titular precisa existir lá antes do credenciamento.                                                                                                                                                                                                                                                                                              | não         |
| `boleto_charge_batch_chunk_invalid`             | 400  | Cada upload de lote deve conter entre 1 e 50 boletos.                                                                                                                                                                                                                                                                                                                                                                                                                 | não         |
| `boleto_charge_batch_empty`                     | 409  | O lote não tem itens para disparar.                                                                                                                                                                                                                                                                                                                                                                                                                                   | não         |
| `boleto_charge_batch_item_conflict`             | 409  | O identifier já existe no lote com outro payload.                                                                                                                                                                                                                                                                                                                                                                                                                     | não         |
| `boleto_charge_batch_item_not_found`            | 404  | Item do lote não encontrado.                                                                                                                                                                                                                                                                                                                                                                                                                                          | não         |
| `boleto_charge_batch_not_editable`              | 409  | Somente lote DRAFT aceita alteração de itens.                                                                                                                                                                                                                                                                                                                                                                                                                         | não         |
| `boleto_charge_batch_not_found`                 | 404  | Lote de Boleto Charge não encontrado nesta conta.                                                                                                                                                                                                                                                                                                                                                                                                                     | não         |
| `boleto_charge_batch_too_large`                 | 400  | O lote aceita no máximo 5.000 boletos.                                                                                                                                                                                                                                                                                                                                                                                                                                | não         |
| `boleto_charge_beneficiary_not_found`           | 404  | Esta conta ainda não tem beneficiário de boleto. O credenciamento ou a primeira emissão cadastra o titular e responde 202 boleto_charge_beneficiary_pending.                                                                                                                                                                                                                                                                                                          | não         |
| `boleto_charge_beneficiary_registration_failed` | 502  | O liquidante recusou o cadastro do beneficiário, na hora ou por webhook nas últimas 24 horas. A mensagem traz o motivo; numa recusa recente, `details.lastEvent` traz `rejectionCode` e `rejectionReason` e o header `Retry-After` traz os segundos até a emissão voltar a recadastrar sozinha. Repetir a emissão antes disso não adianta: corrija os dados da conta e recadastre com `POST .../boleto/charge/beneficiary`, que não espera o prazo. Nada foi emitido. | não         |
| `boleto_charge_beneficiary_transition_invalid`  | 409  | A elegibilidade pedida não é uma transição permitida a partir do status atual. eligible vai para underReview ou ineligible; underReview vai para eligible ou ineligible; ineligible só volta para underReview.                                                                                                                                                                                                                                                        | não         |
| `boleto_charge_issuance_in_progress`            | 409  | Já existe uma emissão em andamento para este identifier.                                                                                                                                                                                                                                                                                                                                                                                                              | sim         |
| `boleto_charge_issuance_outcome_unknown`        | 409  | A tentativa anterior pode ter chegado ao liquidante, mas o resultado não foi confirmado. Não reenvie automaticamente.                                                                                                                                                                                                                                                                                                                                                 | não         |
| `boleto_charge_monthly_limit_exceeded`          | 429  | A emissão não cabe na cota mensal restante do tenant ou da conta. A reserva é atômica e nenhum item do lote foi iniciado.                                                                                                                                                                                                                                                                                                                                             | não         |
| `commercial_policy_staff_required`              | 403  | As cotas comerciais de Boleto Charge e de verificação de identidade só podem ser alteradas por staff CorpX.                                                                                                                                                                                                                                                                                                                                                           | não         |
| `invalid_batch_item`                            | 422  | Um item do lote viola as regras de emissão; a mensagem aponta o índice.                                                                                                                                                                                                                                                                                                                                                                                               | não         |
| `invalid_boleto_charge_policy`                  | 400  | boletoCharge.enabled deve ser booleano e boletoCharge.maxIssuesPerMonth, quando presente, inteiro de 1 a 1000000. Não há modo ilimitado.                                                                                                                                                                                                                                                                                                                              | não         |
| `quota_unavailable`                             | 503  | Não foi possível consultar ou reservar a cota mensal agora.                                                                                                                                                                                                                                                                                                                                                                                                           | sim         |

## Bloqueios de saldo

Bloquear parte do saldo, liberar para outra conta CorpX e cancelar.

| Código                           | HTTP | O que aconteceu e o que fazer                                                                                                                                                 | Retentativa |
| -------------------------------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `account_locked_for_holds`       | 403  | A conta tem trava de saída ativa (bloqueio, horário ou IP de origem) e ela vale para bloquear e liberar saldo. Cancelar um bloqueio continua permitido.                       | não         |
| `hold_managed_by_order`          | 409  | Este bloqueio pertence a uma ordem P2P. Só a ordem o libera ou cancela; use as rotas da ordem.                                                                                | não         |
| `hold_not_active`                | 409  | O bloqueio não está `active`: já foi liberado, cancelado ou está em liberação com outra `Idempotency-Key`. Consulte o hold para ver o estado.                                 | não         |
| `hold_not_found`                 | 404  | Não existe bloqueio com este `holdId` nesta conta.                                                                                                                            | não         |
| `insufficient_available_balance` | 422  | O saldo disponível da conta é menor que o valor do bloqueio. Nada foi bloqueado. Consulte `availableAmount` em `GET /balance`.                                                | não         |
| `release_exceeds_hold`           | 422  | `amount` mais `fee.amount` tem de ser igual ao valor total do bloqueio. Liberação parcial não existe: cancele e crie outro bloqueio.                                          | não         |
| `release_failed`                 | 422  | A transferência da liberação foi recusada e o valor voltou a ficar bloqueado (`active`). `details.cause` traz o motivo. Corrija e libere de novo com outra `Idempotency-Key`. | não         |

## P2P Cripto

Mercado P2P de stablecoins: perfis, carteiras, anúncios, ordens, assinatura e disputas.

| Código                           | HTTP | O que aconteceu e o que fazer                                                                                                                                                                                                                                                                                                                                                | Retentativa |
| -------------------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `ad_closed`                      | 409  | O anúncio foi encerrado e não volta a ser editado. Crie outro.                                                                                                                                                                                                                                                                                                               | não         |
| `ad_not_found`                   | 404  | Não existe anúncio com este `adId` no mercado.                                                                                                                                                                                                                                                                                                                               | não         |
| `ad_suspended`                   | 422  | O anúncio foi suspenso pela CorpX e só a CorpX reativa. Pode ser editado ou fechado, mas não religado.                                                                                                                                                                                                                                                                       | não         |
| `ad_unavailable`                 | 409  | O anúncio não aceita ordem agora: está pausado, sem estoque para o valor, sem preço, com o par desligado, com anunciante não aprovado, com a carteira do anúncio não liberada ou o tenant do anunciante saiu do mercado. Nada foi travado. Liste o mercado de novo.                                                                                                          | não         |
| `advertiser_not_approved`        | 403  | Só anunciante aprovado cria ou reativa anúncio. Peça a aprovação em `POST /p2p/advertiser-requests`.                                                                                                                                                                                                                                                                         | não         |
| `advertiser_request_not_allowed` | 409  | Já existe pedido de anunciante em análise, ou a conta já é anunciante, ou foi suspensa.                                                                                                                                                                                                                                                                                      | não         |
| `amount_above_cap`               | 422  | O valor passa de um teto: por ordem (o menor entre o do mercado e o dos tenants das duas partes), por ordem do anunciante ou diário do comprador (dia em horário de Brasília). A mensagem diz qual.                                                                                                                                                                          | não         |
| `amount_out_of_ad_limits`        | 422  | O valor da ordem fica fora do mínimo e do máximo do anúncio. A mensagem traz a faixa aceita.                                                                                                                                                                                                                                                                                 | não         |
| `contact_already_verified`       | 409  | Este canal do perfil P2P já está confirmado.                                                                                                                                                                                                                                                                                                                                 | não         |
| `contact_code_invalid`           | 422  | Código de confirmação do contato inválido ou expirado.                                                                                                                                                                                                                                                                                                                       | não         |
| `contact_code_locked`            | 422  | Muitas tentativas de código. Peça um código novo.                                                                                                                                                                                                                                                                                                                            | não         |
| `contact_code_rate_limited`      | 429  | Muitos códigos enviados para este contato. Aguarde para pedir outro.                                                                                                                                                                                                                                                                                                         | não         |
| `contact_delivery_failed`        | 503  | Não foi possível enviar o código de confirmação agora. Tente reenviar.                                                                                                                                                                                                                                                                                                       | não         |
| `contract_not_available`         | 409  | A via assinada desta parte ainda não existe: a assinatura não terminou ou está desligada no mercado.                                                                                                                                                                                                                                                                         | não         |
| `delivery_deadline_out_of_range` | 422  | `deliveryDeadlineMin` fica fora da faixa do mercado. A mensagem traz a faixa.                                                                                                                                                                                                                                                                                                | não         |
| `dispute_already_decided`        | 409  | A disputa já foi decidida; não aceita mais mensagem nem evidência.                                                                                                                                                                                                                                                                                                           | não         |
| `dispute_already_open`           | 409  | Já existe disputa aberta nesta ordem.                                                                                                                                                                                                                                                                                                                                        | não         |
| `dispute_not_allowed_yet`        | 409  | Ainda não dá para disputar: o comprador disputa depois do prazo de entrega; o vendedor, 60 minutos depois de enviar ou 24 horas depois da confirmação na rede.                                                                                                                                                                                                               | não         |
| `dispute_not_found`              | 404  | Esta ordem não tem disputa.                                                                                                                                                                                                                                                                                                                                                  | não         |
| `hold_lock_unknown`              | 503  | O banco não confirmou a trava do saldo. A ordem não foi aberta e a CorpX confere o saldo; não repita a ordem antes de consultar o saldo.                                                                                                                                                                                                                                     | não         |
| `holder_only`                    | 403  | Só o titular da conta faz esta operação. O documento em `X-Acting-Document` é de outra pessoa.                                                                                                                                                                                                                                                                               | não         |
| `holds_unavailable`              | 503  | O serviço de bloqueio de saldo está indisponível. A ordem não foi aberta.                                                                                                                                                                                                                                                                                                    | não         |
| `invalid_network`                | 422  | A rede da carteira não é aceita. Consulte as redes em `GET /p2p/pairs`.                                                                                                                                                                                                                                                                                                      | não         |
| `invalid_offset`                 | 422  | `offset` deve ficar dentro de 5% do spot da Binance no momento (o mesmo teto dos 500 bps). A mensagem traz o limite em reais, com 4 casas.                                                                                                                                                                                                                                   | não         |
| `invalid_spread`                 | 422  | `spreadBps` deve ficar entre -500 e 500.                                                                                                                                                                                                                                                                                                                                     | não         |
| `invalid_username`               | 422  | `username` aceita de 3 a 24 caracteres: letras minúsculas, dígitos, `_` e `.`.                                                                                                                                                                                                                                                                                               | não         |
| `invalid_wallet_address`         | 422  | O endereço não é válido para a rede informada.                                                                                                                                                                                                                                                                                                                               | não         |
| `order_not_cancellable`          | 409  | A ordem não pode mais ser cancelada: o contrato já foi assinado pelas duas partes ou ela terminou.                                                                                                                                                                                                                                                                           | não         |
| `order_not_concluded`            | 409  | O comprovante só sai com a negociação concluída: liberada, assinada pelas duas partes, vendedor pago e taxa cobrada.                                                                                                                                                                                                                                                         | não         |
| `order_not_found`                | 404  | Não existe ordem com este `orderId` em que esta conta seja parte.                                                                                                                                                                                                                                                                                                            | não         |
| `order_role_not_allowed`         | 403  | Esta etapa é da outra parte: o vendedor informa o txid e o comprador libera o valor.                                                                                                                                                                                                                                                                                         | não         |
| `order_step_out_of_order`        | 409  | A ordem não está na etapa que esta chamada exige. Consulte a ordem para ver o `status`.                                                                                                                                                                                                                                                                                      | não         |
| `order_unavailable`              | 503  | A ordem não pôde ser aberta por falha temporária. Nada ficou travado; tente de novo com outra `Idempotency-Key`.                                                                                                                                                                                                                                                             | não         |
| `p2p_contact_unverified`         | 422  | E-mail ou telefone do perfil P2P ainda não foi confirmado. Confirme os dois antes de anunciar ou negociar.                                                                                                                                                                                                                                                                   | não         |
| `pair_not_enabled`               | 422  | O par (cripto e rede) não está habilitado no mercado.                                                                                                                                                                                                                                                                                                                        | não         |
| `price_evidence_not_found`       | 404  | A ordem existe, mas não tem evidência de cotação registrada. Acontece só em ordens abertas antes de a evidência passar a ser gravada.                                                                                                                                                                                                                                        | não         |
| `price_unavailable`              | 409  | A Binance não respondeu com o preço spot no momento da abertura (tempo esgotado, erro HTTP, limite de requisições ou resposta inválida). A ordem exige essa consulta, inclusive em anúncio de preço fixo, porque a cotação do momento fica registrada como evidência. Nenhuma ordem foi criada e nada foi travado. Repita o pedido em instantes com a mesma Idempotency-Key. | não         |
| `profile_not_found`              | 404  | Não existe perfil P2P público com este `username`.                                                                                                                                                                                                                                                                                                                           | não         |
| `screening_unavailable`          | 503  | A triagem de risco das carteiras está indisponível. A ordem não foi aberta; tente de novo em instantes.                                                                                                                                                                                                                                                                      | não         |
| `self_trade`                     | 409  | A conta tentou negociar com o próprio anúncio ou com anúncio de outra conta do mesmo titular.                                                                                                                                                                                                                                                                                | não         |
| `signer_contact_missing`         | 422  | O perfil P2P não tem e-mail e telefone confirmados para assinar o contrato. A ordem não foi aberta; confirme o contato no perfil P2P antes de negociar.                                                                                                                                                                                                                      | não         |
| `stock_below_reserved`           | 422  | O estoque não pode ficar abaixo do que já está reservado em ordens abertas.                                                                                                                                                                                                                                                                                                  | não         |
| `term_not_available`             | 409  | O termo de consolidação ainda não existe: a negociação não concluiu ou o PDF ainda não foi gerado.                                                                                                                                                                                                                                                                           | não         |
| `txid_already_used`              | 409  | Este txid já foi informado em outra ordem.                                                                                                                                                                                                                                                                                                                                   | não         |
| `txid_invalid_format`            | 422  | O txid não tem o formato da rede do par (Tron: 64 caracteres hexadecimais).                                                                                                                                                                                                                                                                                                  | não         |
| `txid_limit_reached`             | 422  | A ordem já recebeu o máximo de txids. Abra uma disputa se a transferência não aparecer.                                                                                                                                                                                                                                                                                      | não         |
| `username_change_too_soon`       | 409  | O `username` já foi trocado nos últimos 90 dias. Criar o perfil não conta; cada troca abre uma carência de 90 dias. `details.nextChangeAt` traz a data a partir da qual a troca volta a valer.                                                                                                                                                                               | não         |
| `username_required`              | 409  | Defina o `username` do perfil P2P antes de pedir para anunciar.                                                                                                                                                                                                                                                                                                              | não         |
| `username_taken`                 | 409  | Outro perfil do mercado já usa este `username`. O `username` é único entre todos os tenants.                                                                                                                                                                                                                                                                                 | não         |
| `wallet_already_registered`      | 409  | Esta carteira já está cadastrada nesta conta.                                                                                                                                                                                                                                                                                                                                | não         |
| `wallet_in_open_order`           | 409  | A carteira está em uma ordem em andamento ou é a carteira de um anúncio ativo. Espere a ordem terminar ou troque a carteira do anúncio.                                                                                                                                                                                                                                      | não         |
| `wallet_not_approved`            | 422  | A carteira não passou na triagem de risco ou ainda está em análise. Na abertura de ordem, `details.walletOf` diz de quem é a carteira recusada (`taker` ou `maker`).                                                                                                                                                                                                         | não         |
| `wallet_not_found`               | 404  | Não existe carteira com este `walletId` nesta conta.                                                                                                                                                                                                                                                                                                                         | não         |