Skip to main content

​
HTTP status codes

CodeMeaningAction
200SuccessProcess the response
400Bad requestCheck request body — missing or invalid parameters
401UnauthorizedCheck your API Key and Secret
403ForbiddenYour account lacks access to this endpoint or feature
404Not foundInvalid endpoint URL or resource doesn’t exist
409ConflictDuplicate clientId — this customer already has an active session
429Rate limitedSlow down — wait and retry with exponential backoff
500Server erroriDenfy issue — retry after a short delay, contact support if persistent

​
Common errors and fixes

Cause: Wrong API Key or Secret, or using sandbox keys against production (or vice versa).Fix:
  1. Verify your API Key and Secret in Dashboard → Settings → API Keys
  2. Ensure you’re using the correct environment keys
  3. Check that the Authorization header is correctly Base64-encoded as key:secret
Cause: You’re generating a token for a clientId that already has an active verification session.Fix:
  • Use a unique clientId per verification attempt
  • If the customer needs to re-verify, either use a different clientId or wait for the previous session to expire
Cause: A required field is missing or a field value is invalid.Fix:
  • Check the token parameters for required fields and valid values
  • Ensure clientId is a non-empty string
  • Ensure country codes use ISO 3166-1 alpha-2 format
Possible causes:
  1. Webhook URL not configured — check Dashboard → Settings → Webhooks)
  2. Your endpoint returned a non-2xx status — check server logs
  3. Firewall blocking iDenfy IPs — whitelist our IP ranges
  4. HTTPS certificate issue — ensure your cert is valid and not self-signed
  5. Webhook still processing — manual reviews can take several minutes
Cause: Browser security policies restrict camera access in third-party iFrames.Fix:
  • Add allow="camera; microphone" to the iFrame tag
  • Ensure your page is served over HTTPS
  • Check that no Permissions-Policy header blocks camera access
  • Some browsers (Safari) have stricter iFrame policies — test across browsers

​
Retry strategy

For transient errors (429, 500, network timeouts), implement exponential backoff: 
import time
import requests

def call_with_retry(url, payload, auth, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, json=payload, auth=auth)

        if response.status_code == 200:
            return response.json()
        elif response.status_code in (429, 500, 502, 503):
            wait = 2 ** attempt  # 1s, 2s, 4s
            time.sleep(wait)
        else:
            response.raise_for_status()

    raise Exception(f"Failed after {max_retries} retries")

​
Full error reference

See Standard Error Messages for the complete list of error codes and their descriptions.