Tratamento de Erros

Todas as respostas de erro da API seguem um formato JSON padronizado para facilitar o tratamento programático.

Formato do Erro

{
  "errorCode": "missing_tenant",
  "message": "X-Tenant-Id header is required"
}

O contrato estável é o errorCode — trate por ele. A message é texto de apresentação em PT-BR e pode ser reescrita sem aviso.

Quando o erro tem origem no liquidante (nosso parceiro bancário), a resposta traz também um bloco partner com o código e a mensagem crus dele, para você diagnosticar sem abrir ticket:

{
  "errorCode": "limit_exceeded_daily",
  "message": "O valor excede o limite diurno desta conta. Limite restante: R$ 0,00.",
  "partner": {
    "code": "request.query.daily_limit_exceeded",
    "message": "O valor R$ 1.000,00 excede seu limite diurno de pagamentos por Pix. Limite restante: R$ 0,00"
  }
}

O bloco partner é informativo: use-o em log e suporte, nunca como chave de decisão no seu código. Ele pode conter code, message e field (o campo apontado pelo liquidante), e é omitido quando o liquidante não detalha o motivo.

Catálogo Geral de Erros

Code	HTTP	Descrição
missing_tenant	400	O header X-Tenant-Id é obrigatório e não foi informado.
tenant_mismatch	403	O X-Tenant-Id não corresponde ao tenant da conta no path (ou ao tenantId do body).
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.
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.
tenant_disabled	403	O tenant está desativado: nenhuma rota da API responde. Fale com o suporte CorpX para reativar o acesso.
account_not_found	404	O accountId do path não existe.
not_found	404	O recurso solicitado não existe.
invalid_payload	400	O corpo da requisição (JSON) é inválido ou contém erros de validação.
invalid_body	400	O corpo não é um JSON válido.
missing_fields / missing_field	400	Campos obrigatórios ausentes. A mensagem nomeia quais.
invalid_field	400	Um campo tem valor fora do formato ou do limite aceito. A mensagem nomeia o campo e o limite.
idempotency_conflict	409	Em POST /v1/accreditations/biometry-evidence, o evidenceId derivado da Idempotency-Key já pertence a outro tenant. 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.
invalid_state	409	A operação não se aplica ao estado atual do recurso.
forbidden	403	Você não tem permissão para realizar esta ação no recurso solicitado.
unauthorized	401	Header Authorization ausente. Token inválido ou expirado retorna 403 (obtenha um novo token via client_credentials).
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.
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).
db_unavailable / banking_unavailable / temporal_unavailable	503	Dependência interna indisponível no momento. Pode ser repetido.
db_error	500	Erro interno de persistência.
internal_error	500	Ocorreu um erro inesperado em nossos servidores.
workflow_start_failed / workflow_signal_failed	502	Falha ao iniciar ou sinalizar o fluxo interno da operação; repita a requisição com a mesma Idempotency-Key.

Erros do Liquidante

Esta é a lista completa dos errorCode que representam recusa ou falha no liquidante, e não na validação da CorpX. Ela é gerada a partir do catálogo do próprio código, então não divergirá do que a API emite de fato.

Dois pontos importantes:

• O HTTP é o nosso, não o do liquidante. O parceiro devolve 403 para limite estourado, o que muitos clientes leem como falha de autenticação; nós devolvemos 422. Da mesma forma, 410 Gone de QR Code removido sai como 409, e qualquer 5xx do parceiro sai como 502.
• Retentativa na coluna abaixo indica se repetir a mesma requisição (com a mesma Idempotency-Key) pode dar um resultado diferente. Onde estiver "não", corrija o dado ou a condição antes de reenviar.

Os mesmos códigos aparecem nos webhooks de falha, em data.errorCode, com o bloco data.partner correspondente.

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	Limite da janela diurna (06:00–20:00). A mensagem traz o limite restante quando o liquidante informa.	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
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

Erros Específicos de Negócio

PIX Out (Transferências)

Code	HTTP	Descriçã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.
invalid_identifier	400	O identifier excede o tamanho aceito ou usa caracteres não permitidos.
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.
invalid_field	400	Limite conhecido do liquidante barrado antes do envio — description acima de 140 caracteres ou branch/accountBranch acima de 4 dígitos.
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. O motivo ratio (maxLookupRatio) foi descontinuado na v2.53.0 e não aparece mais.
beneficiary_not_found	404	O beneficiário informado não existe no cadastro da conta.
beneficiary_incomplete	422	O beneficiário cadastrado não tem todos os dados necessários para a operação escolhida.
beneficiary_not_active_at_partner	422	O beneficiário existe no cadastro mas ainda não está ativo no liquidante.
batch_too_large	400	BigPix: o valor pedido geraria mais de 99 parcelas.
batch_not_found	404	BigPix: o batchId consultado não existe.

Saldo, limites, chave PIX e recusa do parceiro saem com os códigos da seção Erros do Liquidante.

QR Code

Code	HTTP	Descrição
missing_field	400	pixKey ausente — e, no QR dinâmico, value ausente ou não positivo.
invalid_field	400	message acima de 140 caracteres, limite do liquidante.
invalid_identifier	400	O identifier excede o tamanho aceito ou usa caracteres não permitidos.
invalid_payload	400	expirationDate fora do formato RFC 3339 ou no passado.
missing_param	400	Consulta e cancelamento exigem o query param identifier (alias txid).
policy_denied	422	Regra de política recusou a criação (qrCode.canCreateStatic, qrCode.canCreateDynamic, qrCode.minAmount, qrCode.maxAmount).

Chaves PIX

Code	HTTP	Descrição
invalid_body	400	O corpo não é um JSON válido.
missing_field	400	keyType ausente, ou pixKey ausente para um tipo que não é random.
invalid_pix_key	400	A chave no path não pôde ser decodificada (lembre de aplicar URL-encode em e-mail e telefone).
policy_denied	422	Regra de política recusou a criação (keys.canCreate, keys.maxKeys).

O formato da chave em si é validado pelo liquidante e volta como invalid_pix_key; o limite de chaves por conta dele, como pix_key_limit_exceeded.

Devoluções (PIX Refund)

Code	HTTP	Descrição
invalid_payload	400	reason ausente ou fora da lista oficial de motivos de devolução.
original_transaction_not_found	404	A transação original (originalEndToEnd) não foi encontrada.

refund_amount_exceeded (valor acima do original ou do saldo ainda devolvível) vem do liquidante — ver a seção anterior. partial_refund_not_supported deixou de ser retornado: estorno parcial passou a ser aceito.

A devolução iniciada pela API também passa pela policy: policy_denied (422) quando a seção Estorno está desligada (refund.disabled) ou o valor excede refund.maxAmount.

TED

Code	HTTP	Descrição
invalid_bank_code	400	bankCode deve ser o Compe de 3 dígitos. TED não aceita ISPB — o contrato do liquidante não tem esse campo, e enviá-lo deixaria a TED pendurada.
invalid_account_type	400	accountType deve ser CHECKING, SAVINGS, PAYMENT ou SALARY. Omitido, vale CHECKING.
invalid_tax_number	400	taxNumber deve ter 11 (CPF) ou 14 (CNPJ) dígitos.
invalid_identifier	400	O identifier excede o tamanho aceito ou usa caracteres não permitidos.
invalid_field	400	description acima de 140 caracteres ou branch acima de 4 dígitos (envie a agência sem o dígito verificador).
missing_fields	400	Falta value, holderName, branch ou account.

A TED deduplica pelo identifier e nunca reexecuta — reenviar um identifier já usado devolve 200 com o estado atual, inclusive quando é de falha. Ver Idempotência.

Transferência Interna

Code	HTTP	Descrição
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).

A recusa do liquidante sai como 422 com status: "FAILED" e o código da seção Erros do Liquidante — normalmente insufficient_funds ou partner_rejected.

Extrato, Lançamentos e Exportações

Code	HTTP	Descrição
invalid_date_range	400	startDate / endDate fora do formato YYYY-MM-DD.
date_range_too_wide	400	A janela do extrato passa de 31 dias. Quebre em períodos menores.
invalid_operation	400	O detalhe do lançamento exige o query param operation: PIX, TED, BOLETO, INTERNAL ou FEE.
invalid_query	400	A timeline por conta exige exatamente um entre endToEndId e identifier — nunca os dois, nunca nenhum.
invalid_format	400	format da exportação deve ser csv ou pdf.
not_ready	409	O download foi pedido antes de a exportação ficar pronta. Consulte o status até completed.
presign_failed	500	Falha ao gerar o link de download do arquivo já pronto. Pode ser repetido.

Webhooks (subscriptions)

Code	HTTP	Descrição
missing_field	400	url ausente na criação da subscription.
invalid_url	400	A url precisa usar https://.
hookdeck_sync_failed	502	Falha ao registrar o destino no nosso entregador de webhooks. Pode ser repetido.

Credenciamento / Abertura de Contas

Erros dos endpoints POST /v1/accreditations/pf|pj, POST /v1/accreditations/biometry-evidence, POST /v1/accreditations/{id}/persons/{cpf}/retry e consultas.

Code	HTTP	Descriçã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.)
missing_fields	400	Campos obrigatórios ausentes (ex.: documentType, document, legalName; PF: person.cpf; PJ: company.cnpj e ao menos um partner).
invalid_document_type	400	documentType inválido — use CPF ou CNPJ.
invalid_document	400	Documento com contagem de dígitos inesperada (CPF=11, CNPJ=14).
invalid_field	400	Limite do liquidante barrado no POST: address.number acima de 10 caracteres (mova o excedente para address.complement) ou address.cityIbgeCode sem 7 dígitos / incoerente com address.state. Um address.complement com menos de 3 caracteres não é erro: o campo é opcional no liquidante e é omitido no envio.
mixed_biometry_mode	422	PJ: todos os sócios devem usar o mesmo modo de biometria (todos unico ou todos BYO), sem misturar.
unsupported_provider	422	Provedor de biometria BYO não reconhecido. Aceitos: unico, serpro, idwall, sumsub, clearsale, caf, valid.
provider_not_enabled	422	O provedor BYO informado não está habilitado para o seu tenant.
evidence_not_found	422	O biometry.evidenceId não existe (ou não pertence ao seu tenant). Faça o upload em POST /v1/accreditations/biometry-evidence primeiro.
not_pj	422	Upload de documentos societários só é aceito em accreditation PJ (POST .../documents).
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.
invalid_content_type	422	contentType deve ser application/pdf no upload de documentos societários.
invalid_state	409	Operação não aplicável ao estado atual (ex.: retry de biometria já aprovada, ou accreditation em estado terminal).
invalid_status	409	Upload de documentos societários bloqueado no status atual (só PENDING_BIOMETRY / BIOMETRY_APPROVED / PENDING_REVIEW).
not_found	404	Accreditation (ou pessoa dentro dela) não encontrada.
rate_limited	429	Muitos pedidos de autorização de CPF que já tem conta na última hora. Tente mais tarde; picos sustentados são analisados pela CorpX.
presign_error	500	Falha ao gerar o link de upload da evidência ou do documento societário. Pode ser repetido.
storage_unavailable	503	Arquivo KYC (bucket de evidências) indisponível no momento.
workflow_signal_failed	502	Falha ao sinalizar o fluxo de credenciamento; tente novamente.

Erros de validação da CorpX nestes mesmos endpoints, com o texto gerado a partir do catálogo do próprio código:

Código	HTTP	O que aconteceu e o que fazer	Retentativa
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). A URI precisa ser registrada pelo suporte da CorpX antes do primeiro uso, e a comparação é exata. Ver Retorno ao seu app.	não

A recusa do credenciamento pelo liquidante chega de forma assíncrona, no webhook accreditation.failed e no GET /v1/accreditations/{id}, em reason:

Reason	O que aconteceu
partner_validation_failed	O liquidante recusou um campo do cadastro. A mensagem nomeia o campo e o bloco partner traz a validação original.
existing_partner_account	O documento já tem conta no liquidante — é necessário transferir o controle via suporte.
partner_unavailable	Indisponibilidade do liquidante. É transitório: reenvie o credenciamento.
partner_rejected	Recusa por política/risco do liquidante, sem campo específico.

Exemplos de Erros Comuns

Saldo Insuficiente

{
  "errorCode": "insufficient_funds",
  "message": "Saldo insuficiente na conta do liquidante para concluir a operação.",
  "partner": {
    "code": "request.client.insufficient_balance",
    "message": "Saldo insuficiente para realizar a operação"
  }
}

Campo Acima do Limite do Liquidante

{
  "errorCode": "invalid_field",
  "message": "O campo \"Identifier\" não é aceito pelo liquidante com o valor enviado. O valor deve ter no máximo 50 caracteres.",
  "partner": {
    "code": "request.value.above_maximum",
    "field": "Identifier",
    "message": "O valor 'Identifier' deve ter no máximo 50 caracteres."
  }
}

Conflito de Idempotência

{
  "errorCode": "idempotency_conflict",
  "message": "Request with same Idempotency-Key but different payload"
}

Escopo Insuficiente

{
  "errorCode": "insufficient_scope",
  "message": "esta credencial não tem escopo para esta operação; é necessário o escopo qrcode.manage"
}

Crie uma credencial com o escopo indicado no painel do backoffice (API Credentials). Escopos que movimentam dinheiro são emitidos pela CorpX.

Monitoramento e Suporte

Se você receber erros 5xx frequentes (internal_error, partner_error, partner_unavailable, partner_internal), recomendamos:

1. Implementar retry exponencial com a mesma chave de idempotência (máximo de 3 tentativas), apenas nos códigos marcados como retentáveis.
2. Verificar o status da nossa plataforma em caso de indisponibilidade prolongada.
3. Entrar em contato com o suporte informando:
   • O errorCode recebido e o bloco partner, quando houver
   • O payload enviado (sem dados sensíveis)
   • O X-Request-Id da resposta (se disponível)
   • Timestamp aproximado do erro

Canais de Suporte

• Slack: Canal privado por cliente — solicite acesso durante o onboarding.
• Email: api@corpx.com