Skip to main content

Troubleshooting

This section describes the main errors related to the use of mTLS, their possible causes, and how to resolve them.

The API authentication mechanism uses combined security layers:

  • API Key (x-delbank-api-key)
  • Account identification (x-delfinance-account-id)
  • Client certificate (mTLS)
  • Allowlist de IP

mTLS validation flow

The mTLS verification validates the following parameters:

  1. The client presented a certificate
  2. The certificate was validated by the CA
  3. The certificate has not been revoked
  4. The certificate serial number
  5. The certificate's SHA256 fingerprint

If any check fails, the request will be denied.

Common errors

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

Example​

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

Cause​

The request did not include the mandatory API header.

Solution​

Add the header:

x-delbank-api-key: YOUR_API_KEY

Example with curl:

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

2. API key is blocked​

Example​

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

Cause​

The key has been blocked for security reasons.

Common reasons:

  • Too many invalid attempts
  • Manual block
  • Security policy

Solution​

Contact Delfinance support to request an unblock.

3. Valid client certificate required (mTLS)​

Example​

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

Cause​

The API requires mTLS, but:

  • No certificate was sent
  • The certificate is invalid
  • The TLS handshake failed

Solution​

Verify if the request is sending the certificate:

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

Or using a .p12 file:

curl https://api.delfinance.com.br/v1/resource   --cert-type P12   --cert certificate.p12:password   -H "x-delbank-api-key: YOUR_API_KEY"

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

Example​

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

Cause​

In addition to the certificate being valid, it must match the:

  • Serial Number
  • SHA256 Fingerprint

registered for that specific API Key.

How to check the fingerprint​

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

Solution​

Ensure that:

  • The certificate sent is the same one that was registered
  • The fingerprint is identical
  • The serial number matches

If you have changed your certificate, request an update to your registration.

5. IP not allowed for this API key​

Example​

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

Cause​

The request's originating IP is not permitted.

Solution​

Request the inclusion of the outbound IP in the IP allowlist.

6. Invalid or inexistent account_id​

Example​

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

Cause​

The provided x-delfinance-account-id does not correspond to the API Key.

Solution​

Ensure that the x-delfinance-account-id header is present and matches the provided API Key.

7. Validation expired​

Example​

{
  "message": "Validation expired"
}

Solution​

Retry the request.

Diagnostic Checklist

Before opening a support ticket, please verify:

  • Correct API Key
  • x-delbank-api-key header sent
  • x-delfinance-account-id header correct
  • Valid certificate
  • Certificate is not expired
  • Certificate matches the registered one
  • IP is authorized
  • mTLS correctly configured in the HTTP client

Useful Information for Support

If you need to open a support ticket, please provide:

  • Endpoint used
  • Timestamp of the request
  • Originating IP
  • Account ID
  • API Key (partial)
  • Ray ID (if available)
  • The returned error log