This article covers common issues that may occur when using the Cognism API and explains how to resolve them.

Most API issues are caused by authentication problems, expired API tokens, insufficient Bulk Credits, API Entitlements, or invalid request formatting.

Before you troubleshoot

Before investigating an API issue, check that:

• Your organisation has API access enabled.
• You are using a valid API token.
• Your API token has not expired.
• You have sufficient Bulk Credits available.
• The data you are requesting is included in your API Entitlements.
• Your request matches the endpoint requirements documented in the Cognism Developer Portal.

Authentication failed (401 Unauthorized)

Symptoms

Your API request returns a 401 Unauthorized response.

Cause

The API request could not be authenticated.

Common causes include:

• An invalid API token.
• An expired API token.
• A missing Authorization header.
• An incorrectly formatted Bearer token.
• Missing Entitlements

Resolution

Verify that:

• Your API token is valid.
• The token has not expired.
• The Authorization header is included in every request.
• Reach out to your account manager and Support Team to set Entitlements.
• The header uses the following format:

Authorization: Bearer <YOUR_API_TOKEN>

If necessary, generate a new API token and update your integration.

No records returned

Symptoms

The Search API or Enrich API returns no matching records.

Cause

No suitable match was found based on the supplied search criteria.

For the Enrich API, this may also occur if the Match Score is below the configured minimum.

Resolution

Try the following:

• Provide additional search criteria.
• Use unique identifiers such as an email address, company domain, website, or LinkedIn URL.
• Reduce the number of search filters if they are too restrictive.
• Review your configured minimum Match Score if using the Enrich API.

Missing data in the Redeem response

Symptoms

The Redeem API successfully returns a record, but expected fields are missing.

Cause

The missing fields are not included in your organisation's API Entitlements.

The Redeem API only returns data that your organisation is licensed to access.

Resolution

Review your configured API Entitlements.

If additional data fields are required, contact your Account Manager to discuss updating your API Entitlements.

Bulk Credits are being consumed

Symptoms

Bulk Credits decrease after API requests.

Cause

Bulk Credits are consumed when redeeming contact records.

This is expected behaviour.

Search and Enrich requests do not consume Bulk Credits.

Resolution

To reduce Bulk Credit consumption:

• Use the Search or Enrich API to verify records before redeeming them.
• Redeem only the contacts you need.
• Reuse previously redeemed contacts where possible, as repeat redemptions do not consume additional Bulk Credits.

Rate limit exceeded

Symptoms

API requests begin failing after a high volume of requests.

Cause

Your application has exceeded the rate limits for the API endpoint being used.

Resolution

Reduce the frequency of API requests and implement retry logic in your application.

If you're processing large volumes of data, batch requests appropriately and stay within the published limits for each endpoint.

Refer to the Cognism Developer Portal for the latest rate limits and best practices.

Invalid Redeem ID

Symptoms

The Redeem API returns an error indicating that the Redeem ID is invalid.

Cause

The Redeem ID is incorrect, incomplete, or was not returned by the Search API or Enrich API.

Resolution

Use the Redeem ID exactly as returned in the Search or Enrich API response.

If necessary, perform a new Search or Enrich request to generate a new Redeem ID.

Invalid request

Symptoms

The API returns a 400 Bad Request response.

Cause

The request body is invalid or required parameters are missing.

Resolution

Review the endpoint documentation and verify that:

• All required fields are included.
• Parameter names are correct.
• The request body is valid JSON.
• Data types match the endpoint specification.

Still experiencing issues?

If the issue persists after completing the recommended troubleshooting steps:

• Verify that API access is enabled for your organisation.
• Confirm your API token is valid and has not expired.
• Check that sufficient Bulk Credits are available.
• Review your API Entitlements.
• Validate your request against the Cognism Developer Portal.
• Capture the full API response, including the HTTP status code and response body.
• Contact Cognism Support if you continue to experience issues.

Providing the endpoint used, the HTTP status code, and the complete error response will help speed up troubleshooting.