Erros | API CorpX

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

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_not_found`	404	O `accountId` do path não existe.	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
`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.	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.	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
`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_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
`rate_check_unavailable`	503	Não foi possível validar o limite de jornadas agora. Retente em instantes.	não
`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
`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_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
`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.	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.	não
`invalid_identifier`	400	O `identifier` excede o tamanho aceito ou usa caracteres não permitidos.	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.	não

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

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.	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\	\
`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
`hash_error`	500	Falha interna ao proteger o PIN. Repita; se persistir, acione o suporte.	sim
`invalid_cashout_hours`	422	`cashoutHours` com `HH:MM` inválido, `start` igual a `end`, ou timezone desconhecido.	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_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 nesta conta.	não
`pin_required`	428	A credencial exige `X-Acting-Document` e `X-Transaction-Pin` nas operações de saída.	não
`pin_temporarily_locked`	429	3 tentativas incorretas: bloqueio de 15 minutos. O header `Retry-After` traz os segundos.	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