Pular para o conteúdo principal

Troubleshooting

Este seção descreve os principais erros relacionados ao uso de mTLS, suas possíveis causas e como resolvê-los.

O mecanismo de autenticação da API utiliza camadas de segurança combinadas:

  • API Key (x-delbank-api-key)
  • Identificação da conta (x-delfinance-account-id)
  • Certificado de cliente (mTLS)
  • Allowlist de IP

Fluxo de Validação mTLS

A verificação do mTLS valida alguns parametros:

  1. O cliente apresentou certificado
  2. O certificado foi validado pela CA
  3. O certificado não foi revogado
  4. O serial do certificado
  5. A fingerprint SHA256 do certificado

Se qualquer verificação falhar, a requisição será negada.

Erros Comuns

1. Missing required header: x-delbank-api-key​

Exemplo​

{
  "message": "Missing required header: x-delbank-api-key"
}

Causa​

A requisição não incluiu o header obrigatório da API.

Solução​

Adicionar o header:

x-delbank-api-key: SUA_API_KEY

Exemplo com curl:

curl https://api.delfinance.com.br/v1/resource   -H "x-delbank-api-key: SUA_API_KEY"

2. API key is blocked​

Exemplo​

{
  "message": "API key is blocked"
}

Causa​

A chave de API foi bloqueada por segurança.

Motivos comuns:

  • Muitas tentativas inválidas
  • Bloqueio manual
  • Política de segurança

Solução​

Entrar em contato com o suporte Delfinance para desbloqueio.

3. Valid client certificate required (mTLS)​

Exemplo​

{
  "message": "Valid client certificate required (mTLS)"
}

Causa​

A API exige mTLS, mas:

  • Nenhum certificado foi enviado
  • Certificado inválido
  • Handshake TLS falhou

Solução​

Verifique se a requisição envia o certificado:

curl https://api.delfinance.com.br/v1/resource   --cert client.crt   --key client.key   -H "x-delbank-api-key: SUA_API_KEY"

Ou usando arquivo .p12

curl https://api.delfinance.com.br/v1/resource   --cert-type P12   --cert certificado.p12:senha   -H "x-delbank-api-key: SUA_API_KEY"

4. Client certificate does not match allowed certificate (mTLS STRICT)​

Exemplo​

{
  "message": "Client certificate does not match allowed certificate (mTLS STRICT)"
}

Causa​

Além do certificado ser válido, ele deve coincidir com:

  • O Serial Number
  • A Fingerprint SHA256

registrados especificamente para a sua chave de API.

Como verificar fingerprint​

openssl x509 -in cert.pem -noout -fingerprint -sha256

Solução​

Certifique-se de que:

  • O certificado enviado é o mesmo registrado
  • O fingerprint é idêntico
  • O serial corresponde

Caso tenha trocado o certificado, solicite atualização no cadastro.

5. IP not allowed for this API key​

Exemplo​

{
  "message": "IP not allowed for this API key"
}

Causa​

O IP da requisição não está permitido.

Solução​

Solicitar inclusão do IP de saída na allowlist de IPs.

6. Invalid or inexistent account_id​

Exemplo​

{
  "message": "Invalid or inexistent account_id."
}

Causa​

O x-delfinance-account-id informado não corresponde à API Key.

Solução​

Garantir que o header x-delfinance-account-id esteja presente e correspondente à API Key enviada:

7. Validation expired​

Exemplo​

{
  "message": "Validation expired"
}

Solução​

Refazer a requisição.

Checklist de Diagnóstico

Antes de abrir chamado, verifique:

  • API Key correta
  • Header x-delbank-api-key enviado
  • Header x-delfinance-account-id correto
  • Certificado válido
  • Certificado não expirado
  • Certificado corresponde ao registrado
  • IP autorizado
  • mTLS configurado corretamente no client HTTP

Informações Úteis para Suporte

Caso seja necessário abrir chamado, envie:

  • Endpoint utilizado
  • Horário da requisição
  • IP de origem
  • Account ID
  • API Key (parcial)
  • Ray ID (se disponível)
  • Log do erro retornado