Skip to navigation

Erros

Todos os errorCode que a API devolve, gerados do código que os emite.

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.

{
"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" }
}
CampoO que é
errorCodeCódigo estável. A lista abaixo é gerada do código-fonte do gateway a cada release.
messageExplicação em português, para log e suporte. Não faça parsing.
docsLink para a âncora do código nesta página.
requestIdId da requisição no gateway. Cite ao abrir chamado.
partnerSó 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ódigoHTTPO que aconteceu e o que fazerRetentativa
account_blocked423A 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_balance422POST /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_balance422POST /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_keys422POST /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_missing404O liquidante não devolveu o cadastro do titular desta conta.não
account_not_found404O accountId do path não existe.não
acting_not_holder403X-Acting-Document não é o documento do titular da conta.não
bank_not_found404GET /v1/banks/{code} não achou COMPE nem ISPB no catálogo (ou a linha está desabilitada).não
banking_unavailable503O provedor bancário não está disponível para esta operação neste momento. Repita em alguns segundos; nada foi executado.sim
beneficiary_check_unavailable503Não foi possível confirmar o destino da transferência interna por documento. Retente ou use /transfers/internal/by-bank-account.não
cognito_error502Falha no provedor de identidade ao criar ou alterar a credencial. Repita; se persistir, acione o suporte.sim
cognito_unavailable503Provedor de identidade indisponível. Repita em instantes.sim
credential_revoked403A credencial usada foi revogada. Gere uma nova credencial no internet banking (IB) ou com a CorpX (BaaS).não
db_error500Erro interno de persistência.não
db_unavailable503Banco de dados do gateway indisponível. Nada foi executado; repita em instantes.sim
evidence_not_approved422A 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
forbidden403Você não tem permissão para realizar esta ação no recurso solicitado.não
holder_not_pj422Pedido de atualização cadastral é só de conta PJ. PF usa PUT /holder/address.não
holder_update_closed409O pedido não está no estado que aceita esta ação.não
holder_update_document_type_invalid422documentType não faz parte deste pedido.não
holder_update_documents_missing422Falta documento obrigatório com scanStatus APPROVED.não
holder_update_kind_invalid422kind deve ser address ou registration.não
holder_update_not_found404Pedido de atualização não encontrado nesta conta.não
holder_update_pending409Já existe um pedido aberto do mesmo tipo nesta conta.não
holder_update_required422Conta PJ não altera endereço direto. Abra um pedido em POST /v1/accounts/{accountId}/holder-updates com comprovante.não
idempotency_conflict409A 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.não
identity_not_approved409A 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_stale409A verificação de identidade expirou. A jornada permanece pendente; o titular refaz a captura pelo mesmo link.não
ingest_unavailable503Componente interno de ingestão indisponível. Repita em instantes.sim
init_error500Falha ao inicializar dependências do gateway. Repita; se persistir, acione o suporte com o requestId.sim
insufficient_scope403A 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.não
integrator_credential_required403A 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_error500Ocorreu um erro inesperado em nossos servidores.não
invalid_account400accountId informado para a credencial não é um UUID ou não pertence ao tenant.não
invalid_body400O corpo não é um JSON válido.não
invalid_client400clientId mal formado.não
invalid_path400Um segmento do path está vazio ou mal formado (por exemplo transactionId ausente na timeline).não
invalid_scope400Um dos escopos pedidos para a credencial não existe. Veja a lista em Autenticação.não
invalid_state409A operação não se aplica ao estado atual do recurso.não
marshal_error500Falha interna ao serializar a resposta. Repita; se persistir, acione o suporte com o requestId.sim
med_request_closed409A contestação não está no estado que aceita esta ação.não
med_request_info_missing422Reenviar depois de um pedido de informação exige mensagem ou anexo aprovado.não
med_request_not_found404Contestação não encontrada nesta conta.não
med_request_not_outgoing_pix422Só um PIX enviado por esta conta pode ser contestado.não
med_request_out_of_window422O PIX passou da janela de 80 dias para contestação.não
med_request_pending409Já existe contestação aberta para este endToEndId.não
method_not_allowed405O método HTTP não é aceito nesta rota. Confira o método na referência da API.não
missing_idempotency_key400O header Idempotency-Key é obrigatório.não
missing_tenant400O header X-Tenant-Id é obrigatório e não foi informado.não
no_accounts404O tenant ainda não tem nenhuma conta. Conclua a abertura de conta antes de operar.não
payload_too_large413Corpo 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_found404O endToEndId não é um PIX desta conta.não
rate_check_unavailable503Não foi possível validar o limite de jornadas agora. Retente em instantes.não
request_in_progress409A mesma Idempotency-Key já está em processamento neste tenant. Aguarde e consulte de novo; não é um segundo encerramento.sim
scope_not_self_service403Esse escopo só pode ser concedido pela CorpX, não pela própria credencial.não
storage_error502Falha ao gravar ou ler o arquivo de evidência. Repita; se persistir, acione o suporte.sim
temporal_unavailable503O orquestrador de operações assíncronas não respondeu; a operação não foi iniciada. Repita com a mesma Idempotency-Key.sim
tenant_disabled403O tenant está desativado: nenhuma rota da API responde. Fale com o suporte CorpX para reativar o acesso.não
tenant_forbidden403O 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_mismatch403O X-Tenant-Id não corresponde ao tenant da conta no path (ou ao tenantId do body).não
tenant_suspended403Há 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
unauthorized401Header Authorization ausente. Token inválido ou expirado retorna 403 (obtenha um novo token via client_credentials).não
unsupported_media_type422Tipo de arquivo não aceito para evidência de MED. Envie PDF, PNG ou JPEG.não
user_token_forbidden_on_financial_op403Token de usuário não movimenta dinheiro: operações financeiras exigem credencial de aplicação (client_credentials).não
workflow_start_failed500Não foi possível iniciar a operação assíncrona. Repita com a mesma Idempotency-Key; se persistir, acione o suporte.sim
workflow_timeout504A 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ódigoHTTPO que aconteceu e o que fazerRetentativa
account_not_entitled409O 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_ready409A 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_partner409CPF/CNPJ já credenciado no liquidante por outro participante. Requer transferência de controle via suporte.não
automatic_pix_contract_blocked409O 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_window422O 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_use409O 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_unavailable422O ISPB informado não existe ou não está ativo no Pix Automático. Confira o banco do pagador.não
automatic_pix_receiver_ineligible422O recebedor do Pix Automático precisa ser pessoa jurídica ativa com dados bancários completos no liquidante.não
automatic_pix_recurrence_not_authorized409Agendamentos, postergações e retentativas só valem para recorrência com status authorized.não
automatic_pix_retry_not_allowed409Retentativa 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_conflict409Cada ciclo aceita um agendamento ativo. Postergar só vale enquanto o agendamento está created.não
automatic_pix_value_above_payer_limit422Em 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_mismatch422Recorrê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_content400Conteúdo textual (descrição/mensagem) com caractere não aceito pelo BACEN.não
balance_reservation_failed422Falha na reserva de saldo (saldo bloqueado, em liquidação ou concorrência com outra operação).não
boleto_already_settled409Boleto já baixado/pago. Consulte o pagamento original antes de reenviar.não
boleto_amount_mismatch422Valor divergente do registrado no boleto (considere juros, multa e desconto).não
boleto_charge_barcode_active409O liquidante recusou porque o barcode ainda está ativo.não
boleto_charge_beneficiary_ineligible422O 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_invalid422limitDate do desconto ausente, ilegível ou não anterior a dueDate.não
boleto_charge_identifier_in_use409O liquidante recusou a emissão porque o identifier já está ativo para o beneficiário.não
boleto_charge_not_eligible_for_write_off_cancel409Cancelar baixa exige status writtenOff com baixa no arranjo. Não cancela boleto em aberto.não
boleto_charge_reductions_exceed_amount422A soma das reduções não pode zerar o título.não
boleto_charge_rules_inconsistent422Encargo incompatível com o calculationModel, ou min/max de pagamento inconsistente.não
boleto_scheduled409Existe agendamento ativo para o mesmo código de barras.não
challenge_failure422Falha de PIN/2FA na operação junto ao liquidante.não
conflict409Conflito de estado no liquidante (ex.: recurso já processado).não
identifier_conflict409Identificador (Identifier) já usado no liquidante. Reenviar com o mesmo valor não cria uma nova operação.não
insufficient_funds422Saldo insuficiente apurado pelo liquidante no momento da liquidação.não
invalid_field400Validação de campo específico no liquidante. partner.field indica o campo e a mensagem traz o limite quando informado.não
invalid_payload400O liquidante recusou o corpo da requisição. O bloco partner traz a validação original.não
invalid_pix_key400Formato da chave incompatível com o tipo (CPF, CNPJ, EMAIL, PHONE, EVP).não
key_inactive422Chave existe mas está inativa/em portabilidade. Use outra chave ou dados bancários.não
key_not_found404Chave inexistente no DICT. Confira a digitação ou peça outra chave ao destinatário.não
key_ownership_mismatch422Tentativa de registrar/usar chave cujo documento não é o do titular da conta.não
limit_exceeded422Limite estourado sem discriminação de janela (o liquidante não informou qual).não
limit_exceeded_daily422No 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_monthly422Limite mensal acumulado. Só libera na virada do mês ou com aumento de limite.não
limit_exceeded_nightly422Limite da janela noturna (20:00–06:00), normalmente menor que o diurno.não
limit_exceeded_transaction422Limite por transação. Divida a operação ou solicite aumento de limite.não
not_found404Recurso inexistente no liquidante (id, chave ou transação).não
not_supported501A 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_supported400Legado — não é mais retornado: estorno parcial passou a ser aceito. Um valor acima do original devolve refund_amount_exceeded.não
partner_account_disabled422Conta de origem desabilitada no liquidante (precisa de reativação).não
partner_error502Falha não classificada na comunicação com o liquidante. Pode ser repetida.sim
partner_forbidden502Operação bloqueada pelo liquidante para a conta (produto ou permissão não habilitados).não
partner_internal502Erro interno (5xx) do liquidante. Pode ser repetida.sim
partner_rate_limited429Throttling do liquidante sobre o tráfego da CorpX. Nada no seu pedido está errado — reduza a cadência e repita com backoff.sim
partner_rejected422Recusa do liquidante por política interna, risco ou antifraude. O bloco partner traz o motivo informado.não
partner_unauthorized502Credencial da CorpX junto ao liquidante recusada. Não é problema da sua credencial; aguarde alguns minutos antes de reenviar.não
partner_unavailable502Indisponibilidade ou falha de gateway do liquidante. Pode ser repetida.sim
payer_key_required422A 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_exceeded422Limite de quantidade de chaves por conta (5 para PF, 20 para PJ).não
qr_amount_mismatch422QR Code com valor fixo não aceita valor diferente do original.não
qr_gone409QR Code removido ou expirado no liquidante.não
recipient_account_not_found422Banco/agência/conta de destino inexistente. Aplica-se a TED e transferência interna.não
refund_amount_exceeded400Valor de estorno maior que o saldo estornável do PIX original.não
timeout504Timeout na chamada ao liquidante. A operação pode ter sido criada — consulte antes de reenviar.sim

PIX out

CódigoHTTPO que aconteceu e o que fazerRetentativa
batch_not_found404BigPix: o batchId consultado não existe.não
batch_too_large400BigPix: o valor pedido geraria mais de 99 parcelas.não
beneficiary_incomplete422O beneficiário cadastrado não tem todos os dados necessários para a operação escolhida.não
beneficiary_not_active_at_partner422O beneficiário existe no cadastro mas ainda não está ativo no liquidante.não
beneficiary_not_found404O beneficiário informado não existe no cadastro da conta.não
dict_lookup_limit_exceeded429Os 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.não
invalid_amount400amount ausente, não positivo ou com mais de duas casas decimais.não
invalid_bank_code400No 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.não
invalid_identifier400O 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_policy400pixBatch.maxItems deve ser inteiro entre 1 e 5000 e pixBatch.enabled deve ser booleano.não
pix_batch_account_disabled403PIX 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_required409O dispatch precisa de {“acknowledged”: true} confirmando que o resumo da conferência (valores, saldo e limites) foi lido.não
pix_batch_chunk_invalid400Cada 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_invalid400O 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_empty409O lote não tem itens para conferir ou disparar.não
pix_batch_has_invalid_items409A 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_balance422O saldo disponível no momento do dispatch é menor que o total do lote. Nenhum item foi iniciado.não
pix_batch_item_conflict409O 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_found404Item do lote de PIX não encontrado.não
pix_batch_limit_exceeded422A 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_receipts409Comprovantes só existem para lotes encerrados (COMPLETED, PARTIAL_FAILED ou FAILED) com ao menos um item liquidado.não
pix_batch_not_editable409Só 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_found404Lote de PIX não encontrado nesta conta.não
pix_batch_not_reviewed409O dispatch exige um lote REVIEWED com todos os itens conferidos. Chame POST …/review e aguarde o status.não
pix_batch_receipt_unavailable409O item ainda não liquidou (ou falhou); só itens COMPLETED têm comprovante.não
pix_batch_too_large400O 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_denied422Uma 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.não
receipt_render_failed500Falha ao gerar o PDF do comprovante. Tente novamente; o pagamento em si não é afetado.sim

QR Code

CódigoHTTPO que aconteceu e o que fazerRetentativa
missing_field400pixKey ausente — e, no QR dinâmico, value ausente ou não positivo.não
missing_param400Consulta e cancelamento exigem o query param identifier (alias txid).não

Chaves PIX

CódigoHTTPO que aconteceu e o que fazerRetentativa
key_type_temporarily_unavailable422Cadastro 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ódigoHTTPO que aconteceu e o que fazerRetentativa
med_info_missing422O esclarecimento não pode ser concluído sem mensagem nem anexo novo desde o pedido da análise.não
med_lock_unavailable409A 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_found404A disputa (MED) não existe ou não pertence a esta conta.não
med_not_writable409A 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_us409A 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_invalid422O valor da devolução é obrigatório, positivo e não pode passar do que falta devolver (remaining).não
med_refund_in_progress409Há uma devolução desta disputa ainda em liquidação; aguarde a conclusão antes da próxima etapa.não
med_refund_not_completed409A conta só é liberada depois que a devolução da rodada estiver concluída e o restante retido.não
med_review_not_pending409A 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_order409A 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_found404A transação original (originalEndToEnd) não foi encontrada.não

TED

CódigoHTTPO que aconteceu e o que fazerRetentativa
invalid_account_type400accountType deve ser CHECKING, SAVINGS, PAYMENT ou SALARY. Omitido, vale CHECKING.não
invalid_tax_number400taxNumber deve ter 11 (CPF) ou 14 (CNPJ) dígitos.não
missing_fields400Falta value, holderName, branch ou account.não

Transferência interna

CódigoHTTPO que aconteceu e o que fazerRetentativa
multiple_destination_accounts409Em /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ódigoHTTPO que aconteceu e o que fazerRetentativa
bucket_mismatch409O 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_wide400A janela do extrato passa de 31 dias. Quebre em períodos menores.não
invalid_cursor400O cursor de paginação é inválido ou pertence a outra consulta. Recomece sem cursor.não
invalid_date_range400startDate / endDate fora do formato YYYY-MM-DD.não
invalid_filter400Filtro do extrato avançado inválido (type, direction, status, minAmount/maxAmount ou datas). A mensagem indica o campo.não
invalid_format400format da exportação deve ser csv, pdf ou xlsx.não
invalid_operation400O detalhe do lançamento exige o query param operation: PIX, TED, BOLETO, INTERNAL ou FEE.não
invalid_query400A timeline por conta exige exatamente um entre endToEndId e identifier — nunca os dois, nunca nenhum.não
invalid_s3_key500Referência interna do arquivo de export inválida. Gere o export novamente; se persistir, acione o suporte.sim
missing_account_id400accountId ausente no path. Use GET /v1/accounts/{accountId}/pix/payments/lookup?identifier=....não
missing_identifier400Informe identifier ou endToEnd na query para localizar o pagamento.não
not_ready409O download foi pedido antes de a exportação ficar pronta. Consulte o status até completed.não
presign_failed500Falha ao gerar o link de download do arquivo já pronto. Pode ser repetido.não
statement_rules_unavailable503As 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ódigoHTTPO que aconteceu e o que fazerRetentativa
account_id_required422A credencial está restrita a contas específicas: informe accountId na subscription. Ver Assinatura por conta.não
hookdeck_list_failed502O serviço de entregas não conseguiu listar as tentativas. Repita em instantes.sim
hookdeck_retry_failed502O serviço de entregas recusou o reenvio. Repita em instantes.sim
hookdeck_source_unavailable503Fonte de entregas do tenant indisponível no serviço de webhooks. Repita em instantes.sim
hookdeck_sync_failed502Falha ao registrar o destino no nosso entregador de webhooks. Pode ser repetido.não
hookdeck_unavailable503Serviço de entregas de webhook indisponível. Repita em instantes.sim
invalid_url400A url precisa usar https://.não
missing_delivery_id400deliveryId ausente no path.não
missing_subscription_id400subscriptionId ausente no path.não
no_hookdeck_destination410A subscription não tem mais destino de entrega ativo. Recrie a subscription.não
no_hookdeck_event_found410A entrega saiu da janela de retenção e não pode mais ser reenviada.não
reemit_failed500Falha ao reemitir o evento. Repita; se persistir, acione o suporte com o deliveryId.sim
replay_already_running409Já existe um replay em andamento para esta subscription. Aguarde a conclusão.não
unsupported_auth_type400authType da subscription fora dos valores aceitos (NONE, HMAC, BASIC, BEARER).não

Assinatura de requisição (host assinado)

CódigoHTTPO que aconteceu e o que fazerRetentativa
body_hash_mismatch400O corpo recebido não corresponde ao X-Content-SHA256 assinado.não
credential_not_yet_active403Credencial recém-emitida ainda na carência. Espere o activeFrom devolvido na emissão.não
invalid_ip400Endereç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_key422O 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_derived409O tenant tem credenciais delegadas: a allowlist de IP dele é calculada a partir delas e não aceita edição manual.não
ip_allowlist_required422allowedIps ausente, vazio, com mais de 20 entradas, contendo 0.0.0.0/0 ou prefixo mais largo que /24.não
ip_not_allowed403A requisição saiu de um IP fora da allowlist da credencial.não
last_public_key409Não é possível aposentar a última chave utilizável da credencial.não
public_key_limit_reached409Limite de chaves públicas por credencial atingido. Aposente uma antes de cadastrar outra.não
public_key_required422A emissão de credencial delegada exige publicKeyPem.não
request_signature_invalid403A 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\\
request_signature_required403Falta X-Request-Signature, X-Request-Timestamp ou X-Content-SHA256.não
request_timestamp_skew403X-Request-Timestamp fora da janela de 300s. Sincronize o relógio do servidor (NTP).não
scope_not_delegable403O escopo pedido para a credencial filha não está entre os da credencial que está delegando, ou não é delegável.não
signature_required403A requisição chegou em client.api.corpx.com sem os headers de assinatura. É bloqueio de borda, antes do token.não
signed_host_required403Credencial delegada usada em tenant.api.corpx.com. Repita em client.api.corpx.com, assinando.não
unknown_kid403O 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ódigoHTTPO que aconteceu e o que fazerRetentativa
acting_document_required400Envie X-Acting-Document (CPF do operador) junto com o PIN.não
cashout_locked423O titular bloqueou a saída de dinheiro desta conta (cashoutBlocked).não
cashout_outside_hours403Fora da janela de horário configurada pelo titular. A mensagem traz a janela.não
cashout_source_ip_not_allowed403O 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_found404O clientId do path não existe neste tenant.não
facetec_attempts_exhausted429A 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_unavailable422A 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_progress409Outra captura desta verificação está sendo processada. Aguarde a resposta anterior (até 15 s) antes de enviar outra.sim
facetec_sdk_not_enabled403method: 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_expired409O 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_limited429Renovaçõ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_unavailable503O processamento do FaceTec SDK está temporariamente indisponível no provedor. Tente de novo em instantes.sim
hash_error500Falha interna ao proteger o PIN. Repita; se persistir, acione o suporte.sim
identity_verification_kind_not_enabled403O 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_exceeded429A 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_document400X-Acting-Document deve ser um CPF (11 dígitos) ou CNPJ (14 dígitos).não
invalid_cashout_hours422cashoutHours com HH:MM inválido, start igual a end, ou timezone desconhecido.não
invalid_consume_ttl400consumeTtlMinutes deve estar entre 1 e 60.não
invalid_display_message400displayMessage deve ser texto simples, em uma linha, sem links/markup e com até 240 caracteres.não
invalid_identity_verification_policy400identityVerification 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_justification400justification é obrigatória e tem no máximo 500 caracteres.não
invalid_method400method deve ser link ou facetec_sdk; facetec_sdk exige provider: dracma_trust.não
invalid_provider400provider deve ser unico ou dracma_trust.não
invalid_purpose400purpose não pertence ao enum público de verificação de identidade.não
invalid_reference_id400referenceId deve ter 1–128 caracteres ASCII seguros.não
invalid_reference_match400referenceMatch deve ser none, dracma ou image e só se aplica a method: facetec_sdk.não
invalid_risk400risk.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_ttl400ttlMinutes da verificação deve estar entre 1 e 60.não
limit_request_above_requested422O valor aprovado é maior que o pedido. A aprovação pode ser menor ou igual ao pedido, nunca maior.não
limit_request_bundle_required409O 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_closed409O pedido já foi aprovado, recusado ou cancelado e não aceita nova decisão nem cancelamento.não
limit_request_document_type_invalid422documentType não faz parte do catálogo da conta (PF ou PJ) nem foi pedido pelo analista.não
limit_request_documents_missing422O 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_missing422A 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_current422O valor pedido (ou aprovado) não é maior que o limite efetivo atual da conta.não
limit_request_not_found404O requestId não existe nesta conta.não
limit_request_operation_unavailable422operation 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_pending409Já 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_unavailable503O serviço de limites não respondeu. Repita em instantes.sim
no_pending_change404Não há afrouxamento agendado para cancelar ou antecipar.não
pin_change_disabled403Substituiçã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_invalid403PIN incorreto. A tentativa foi contada.não
pin_locked4236 tentativas incorretas: a liberação exige redefinir o PIN.não
pin_not_found404Não há PIN cadastrado para o operador informado.não
pin_not_set403Este operador não tem PIN cadastrado neste tenant.não
pin_required428A credencial exige X-Acting-Document e X-Transaction-Pin nas operações de saída.não
pin_reset_not_enrolled409Este 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_limited429Muitos pedidos de redefinição de PIN para este operador na última hora. O header Retry-After traz os segundos.sim
pin_temporarily_locked4293 tentativas incorretas: bloqueio de 15 minutos. O header Retry-After traz os segundos.não
provider_error502O provedor de verificação respondeu com erro. partner traz o detalhe cru quando houver. Repita a captura; não conta tentativa.sim
provider_session_starting409A sessão facial já está sendo criada. Retente o mesmo link.sim
provider_session_unavailable409A sessão do provedor não pode ser retomada; abra uma nova verificação.não
provider_unavailable503O provedor de verificação de identidade está indisponível ou não configurado.sim
rate_limited429O limite antifraude da jornada foi atingido. Aguarde a janela indicada e tente novamente.não
reference_already_consumed409Outra prova já foi consumida para este tenant, purpose e referenceId.não
reference_image_required400A verificação foi criada com referenceMatch: image; envie referenceImage (base64 JPEG/PNG) em /facetec/process.não
same_actor422Quem propõe a aprovação não pode ser quem aceita, salvo solo: true quando o aprovador é admin_super.não
verification_expired410O link de verificação expirou ou a jornada já terminou.não
verification_method_mismatch409A rota não se aplica ao method desta verificação: /facetec/* exige facetec_sdk; a página hospedada exige link.não
verification_not_consumable409A verificação não está aprovada/fresca ou não pertence ao purpose e referenceId enviados.não
verification_not_found404A verificação não existe neste tenant. IDs de outro tenant produzem o mesmo 404.não
verification_not_pending409A verificação já chegou a um estado terminal.não
weak_pin422PIN fora da política (6–12 dígitos, sem repetição, sequência, padrão curto ou data de nascimento).não
workflow_unavailable503Não foi possível iniciar o processamento durável da verificação.sim

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ódigoHTTPO que aconteceu e o que fazerRetentativa
boleto_charge_account_disabled403Emissã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_found422O 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_invalid400Cada upload de lote deve conter entre 1 e 50 boletos.não
boleto_charge_batch_empty409O lote não tem itens para disparar.não
boleto_charge_batch_item_conflict409O identifier já existe no lote com outro payload.não
boleto_charge_batch_item_not_found404Item do lote não encontrado.não
boleto_charge_batch_not_editable409Somente lote DRAFT aceita alteração de itens.não
boleto_charge_batch_not_found404Lote de Boleto Charge não encontrado nesta conta.não
boleto_charge_batch_too_large400O lote aceita no máximo 5.000 boletos.não
boleto_charge_beneficiary_not_found404Esta 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_failed502O 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_invalid409A 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_progress409Já existe uma emissão em andamento para este identifier.sim
boleto_charge_issuance_outcome_unknown409A tentativa anterior pode ter chegado ao liquidante, mas o resultado não foi confirmado. Não reenvie automaticamente.não
boleto_charge_monthly_limit_exceeded429A 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_required403As cotas comerciais de Boleto Charge e de verificação de identidade só podem ser alteradas por staff CorpX.não
invalid_batch_item422Um item do lote viola as regras de emissão; a mensagem aponta o índice.não
invalid_boleto_charge_policy400boletoCharge.enabled deve ser booleano e boletoCharge.maxIssuesPerMonth, quando presente, inteiro de 1 a 1000000. Não há modo ilimitado.não
quota_unavailable503Nã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ódigoHTTPO que aconteceu e o que fazerRetentativa
account_locked_for_holds403A 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_order409Este bloqueio pertence a uma ordem P2P. Só a ordem o libera ou cancela; use as rotas da ordem.não
hold_not_active409O 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_found404Não existe bloqueio com este holdId nesta conta.não
insufficient_available_balance422O saldo disponível da conta é menor que o valor do bloqueio. Nada foi bloqueado. Consulte availableAmount em GET /balance.não
release_exceeds_hold422amount 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_failed422A 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ódigoHTTPO que aconteceu e o que fazerRetentativa
ad_closed409O anúncio foi encerrado e não volta a ser editado. Crie outro.não
ad_not_found404Não existe anúncio com este adId no mercado.não
ad_suspended422O anúncio foi suspenso pela CorpX e só a CorpX reativa. Pode ser editado ou fechado, mas não religado.não
ad_unavailable409O 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_approved403Só anunciante aprovado cria ou reativa anúncio. Peça a aprovação em POST /p2p/advertiser-requests.não
advertiser_request_not_allowed409Já existe pedido de anunciante em análise, ou a conta já é anunciante, ou foi suspensa.não
amount_above_cap422O 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_limits422O 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_verified409Este canal do perfil P2P já está confirmado.não
contact_code_invalid422Código de confirmação do contato inválido ou expirado.não
contact_code_locked422Muitas tentativas de código. Peça um código novo.não
contact_code_rate_limited429Muitos códigos enviados para este contato. Aguarde para pedir outro.não
contact_delivery_failed503Não foi possível enviar o código de confirmação agora. Tente reenviar.não
contract_not_available409A via assinada desta parte ainda não existe: a assinatura não terminou ou está desligada no mercado.não
delivery_deadline_out_of_range422deliveryDeadlineMin fica fora da faixa do mercado. A mensagem traz a faixa.não
dispute_already_decided409A disputa já foi decidida; não aceita mais mensagem nem evidência.não
dispute_already_open409Já existe disputa aberta nesta ordem.não
dispute_not_allowed_yet409Ainda 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_found404Esta ordem não tem disputa.não
hold_lock_unknown503O 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_only403Só o titular da conta faz esta operação. O documento em X-Acting-Document é de outra pessoa.não
holds_unavailable503O serviço de bloqueio de saldo está indisponível. A ordem não foi aberta.não
invalid_network422A rede da carteira não é aceita. Consulte as redes em GET /p2p/pairs.não
invalid_offset422offset 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_spread422spreadBps deve ficar entre -500 e 500.não
invalid_username422username aceita de 3 a 24 caracteres: letras minúsculas, dígitos, _ e ..não
invalid_wallet_address422O endereço não é válido para a rede informada.não
order_not_cancellable409A ordem não pode mais ser cancelada: o contrato já foi assinado pelas duas partes ou ela terminou.não
order_not_concluded409O comprovante só sai com a negociação concluída: liberada, assinada pelas duas partes, vendedor pago e taxa cobrada.não
order_not_found404Não existe ordem com este orderId em que esta conta seja parte.não
order_role_not_allowed403Esta etapa é da outra parte: o vendedor informa o txid e o comprador libera o valor.não
order_step_out_of_order409A ordem não está na etapa que esta chamada exige. Consulte a ordem para ver o status.não
order_unavailable503A 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_unverified422E-mail ou telefone do perfil P2P ainda não foi confirmado. Confirme os dois antes de anunciar ou negociar.não
pair_not_enabled422O par (cripto e rede) não está habilitado no mercado.não
price_evidence_not_found404A 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_unavailable409A 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_found404Não existe perfil P2P público com este username.não
screening_unavailable503A triagem de risco das carteiras está indisponível. A ordem não foi aberta; tente de novo em instantes.não
self_trade409A conta tentou negociar com o próprio anúncio ou com anúncio de outra conta do mesmo titular.não
signer_contact_missing422O 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_reserved422O estoque não pode ficar abaixo do que já está reservado em ordens abertas.não
term_not_available409O 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_used409Este txid já foi informado em outra ordem.não
txid_invalid_format422O txid não tem o formato da rede do par (Tron: 64 caracteres hexadecimais).não
txid_limit_reached422A ordem já recebeu o máximo de txids. Abra uma disputa se a transferência não aparecer.não
username_change_too_soon409O 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_required409Defina o username do perfil P2P antes de pedir para anunciar.não
username_taken409Outro perfil do mercado já usa este username. O username é único entre todos os tenants.não
wallet_already_registered409Esta carteira já está cadastrada nesta conta.não
wallet_in_open_order409A 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_approved422A 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_found404Não existe carteira com este walletId nesta conta.não