Troubleshooting

Authentication

CredentialError: Bearer token appears invalid (too short)

You copied a partial token. Re-copy the full JWT from the CDR portal’s Account Details page. Valid tokens start with ey and end with . (trailing period).

CredentialError: JWT token must start with 'ey' and end with '.'

You copied your CDR login password or some other string. A JWT is not a password — generate one from the portal first. See Authentication.

CredentialError: Token is expired or expires within 24 hours

Regenerate the token in the portal. The library treats anything with less than 24 hours remaining as expired; this is deliberate — a token that expires mid-job is worse than one you refreshed an hour early.

401 Unauthorized from a working token

Usually one of:

• Token expired (creds.is_expired?)
• Wrong UserID (case matters — it’s UserID, not UserId or userid). The library handles this, but hits this when you’re calling the API directly.
• Wrong header name (Authentication, not Authorization). Again, the library handles this; a problem only for direct API users.

403 Forbidden

• Missing required headers on a direct API call.
• Occasionally appears when the token was just rotated and the old one is still cached in your session. Rebuild the OAuth2Credentials and retry.

Data shape

Integer values show as 100.0 instead of 100

force_null_types="numpy" (or a library version that defaulted to numpy nulls) produced float columns. Fix:

data = collect_data(..., force_null_types="pandas")

Default in v3.0.0 is "pandas" — so if you’re hitting this, you probably overrode it somewhere.

Empty DataFrame / empty list

Most common causes:

1. The institution didn’t file that period. Check with collect_filers_on_reporting_period() — is the RSSD in the panel?
2. Wrong series. Requesting "ubpr" for a bank that doesn’t have UBPR.
3. Wrong RSSD. Either mistyped, or the RSSD is inactive (merged/closed). Cross- check against the NIC attribute extract.
4. Wrong date format. The API uses MM/DD/YYYY. collect_reporting_periods() returns valid values in the correct format.

NAType error from float(...) conversion

TypeError: float() argument must be a string or a real number, not 'NAType'

You’re calling float() on a pd.NA. Use pd.isna() to check first, or .fillna(...) before the conversion. This is a pandas behavior, not a library bug — see Output formats.

Rate limits

RateLimitError: Retry after N seconds

You exceeded 2,500 requests in the rolling hour. The server’s Retry-After is in the exception; respect it. See Async and rate limits.

Longer-term fix: use RateLimiter(max_requests=2400, window_seconds=3600) and wait_if_needed() before each call.

Intermittent 429s well below 2500/hour

Clock skew between your machine and the FFIEC server. The rolling window is computed server-side; if your clock is five seconds fast, your 2495th call might arrive at what the server considers the 2501st. Drop your effective budget to 2,400/hour.

Network / platform

Windows: SSL: CERTIFICATE_VERIFY_FAILED

The FFIEC endpoint requires a modern SSL trust bundle. Windows is finicky here. Workarounds, in order of preference:

1. Run in WSL2.
2. Use Google Colab.
3. pip install --upgrade certifi and ensure httpx is using it.

ConnectionError / httpx.ConnectTimeout

Network path to ffieccdr.azure-api.us is flaky. Retry with backoff. Corporate proxies sometimes strip headers — if you’re behind one, test from outside the proxy to isolate the cause.

Versioning

AttributeError: module 'ffiec_data_connect' has no attribute 'FfiecDataConnect'

You’re following a v2.x example (or older). v3.0.0 is function-based; there is no FfiecDataConnect class. See Migration from v2.

SOAPDeprecationError: SOAP API support was removed in v3.0.0

Your code still instantiates WebserviceCredentials or FFIECConnection. The FFIEC SOAP API was shut down February 28, 2026. Switch to OAuth2Credentials and JWT. See Migration from v2.

Getting help

Before reaching out, run through this:

1. Read the full upstream troubleshooting guide.
2. Check your credentials: is the token still valid (creds.is_expired)?
3. Test with a different RSSD or reporting period to rule out bad inputs.
4. Search existing GitHub issues: github.com/call-report/ffiec-data-connect/issues.

Then pick the right channel:

• Library bugs / feature requests — open a GitHub issue. Include library version (ffiec_data_connect.__version__), Python version, the full traceback, and a reduced snippet. Anonymize credentials before pasting.
• FFIEC account, portal, or token-generation issues — contact cdr.help@cdr.ffiec.gov. The FFIEC does not support the library itself.
• Private, urgent, or commercial inquiries — see the Support page for direct contact and commercial support options.