---
title: Troubleshooting ChEMBL
description: >-
  Resolve common issues with ChEMBL searches including API errors, rate limits,
  and data interpretation.
tags:
  - chembl
  - troubleshooting
---

This page helps you diagnose the common failure modes of a [ChEMBL](/docs/chembl) search — rate limits and throttling, compounds that return zero results, InChIKey mismatches across databases, large-query timeouts, and how to interpret bioactivity values that seem inconsistent between studies.

## Troubleshooting ChEMBL

This guide covers the most common issues encountered when searching ChEMBL on the platform, along with solutions and workarounds.

## API rate limits and throttling

**Symptom**: Searches return 429 errors or results appear incomplete.

The ChEMBL REST API at EMBL-EBI enforces rate limits to protect shared infrastructure. The platform batches requests internally, but very broad queries can still trigger throttling.

- **Narrow your search**: Add an activity type, raise the potency or pChEMBL threshold, or ask for fewer results. Searching for "all IC50 data" without a target will attempt to retrieve millions of records.
- **Retry after a pause**: Rate limits reset after a short cooldown (typically 30-60 seconds). The platform retries automatically with exponential backoff, but persistent 429s indicate the query scope is too large.
- **Use specific ChEMBL IDs**: Queries by ChEMBL target ID (e.g., CHEMBL203) are faster and less likely to be throttled than free-text gene name searches.

> If you are running many sequential searches (e.g., screening a panel of targets), space them at least 5 seconds apart to stay within rate limits.

## Compound not found

**Symptom**: A compound you expect to find returns zero results.

- **Check the identifier format**: ChEMBL compound IDs start with `CHEMBL` followed by a number (e.g., CHEMBL25 for aspirin). Do not confuse these with PubChem CIDs or DrugBank IDs.
- **Try alternative identifiers**: Search by SMILES, InChIKey, or common name instead of ChEMBL ID. Not all compounds have been assigned ChEMBL IDs.
- **Verify the compound exists in ChEMBL**: ChEMBL only contains compounds from curated literature. Newly synthesized or proprietary compounds will not appear. Check [chembl.gitbook.io](https://chembl.gitbook.io/) for the latest release notes.
- **Canonicalize SMILES**: Non-canonical SMILES may fail exact-match lookups. Use RDKit canonicalization before searching.

## InChIKey mismatches

**Symptom**: The same compound returns different InChIKeys across databases.

InChIKey differences between ChEMBL and PubChem usually stem from stereochemistry or salt/ion handling:

- **Stereochemistry layer**: The first 14 characters of an InChIKey encode the connectivity layer. If these match but the second block differs, the compounds share the same scaffold but differ in stereochemistry.
- **Salt stripping**: ChEMBL stores parent compounds (free base/acid), while some databases index salts. Compare the first block of the InChIKey to check connectivity equivalence.
- **Tautomers**: Different tautomeric forms generate different InChIKeys. ChEMBL normalizes tautomers during curation, but upstream sources may not.

To resolve mismatches, compare the first 14-character block (connectivity layer) rather than the full 27-character InChIKey.

## Large query timeouts

**Symptom**: Searches hang or time out after 30+ seconds.

- **Reduce result scope**: Ask for a potency cutoff (e.g., IC50 < 1000 nM) to limit results. Unfiltered bioactivity queries for popular targets like EGFR can return 50,000+ records.
- **Raise the pChEMBL floor**: Asking for a minimum pChEMBL (e.g., ≥ 6, equivalent to 1 µM) excludes weak-potency records and narrows the result set.
- **Ask for fewer results**: A bioactivity search returns at most 100 records per search (25 by default) — asking for fewer returns faster.
- **Target-first workflow**: Run a target search first to confirm the ChEMBL target ID, then use that ID for a focused bioactivity search. This avoids the slower free-text resolution step.

## Bioactivity data interpretation

**Symptom**: Activity values seem inconsistent or hard to compare across compounds.

### Comparing across studies

Activity values from different assays are not directly comparable. Key factors:

| Factor | Impact |
|--------|--------|
| Assay format | Cell-based IC50 values are typically higher (weaker) than biochemical IC50 |
| Assay conditions | Temperature, pH, substrate concentration all affect measured values |
| Activity type | IC50, Ki, Kd, and EC50 measure fundamentally different things |
| Units | Most values are in nM, but check -- some older entries use uM or M |

### Best practices for comparison

- Filter by a **single activity type** (e.g., only IC50) when ranking compounds
- Use **confidence ≥ 7** to ensure target assignment is reliable
- Check the **assay description** for context on experimental conditions
- For published SAR, look for compounds tested in the **same assay** (same assay ChEMBL ID)

### Activity value ranges

| Range (nM) | Interpretation |
|------------|---------------|
| < 10 | Highly potent (clinical candidate range) |
| 10-100 | Potent (typical lead compound) |
| 100-1000 | Moderate (hit-to-lead stage) |
| 1000-10000 | Weak (screening hit) |
| > 10000 | Inactive or very weak |

## Missing or incomplete data

**Symptom**: Expected fields (e.g., SMILES, molecular weight) are null.

- **Confidential structures**: Some ChEMBL entries from journal publications have redacted structures. The bioactivity data exists but the compound structure is marked confidential.
- **Peptides and biologics**: Large molecules (peptides, antibodies) may lack SMILES representations. Check for InChI or sequence-based identifiers instead.
- **Assay-level gaps**: Not all assays report all fields. `pchembl_value` and `standard_units` may be null for older entries.

## When to retry vs. adjust

- **Retry**: Transient 429/500 errors, network timeouts, or intermittent API unavailability.
- **Adjust query**: Zero results with valid identifiers, consistent timeouts on broad queries, or unexpected data volumes.
- **Switch tools**: If you need computed properties (logP, TPSA) rather than measured bioactivity, use PubChem. If you need regulatory approval data, use DrugCentral.

## Getting help

If issues persist:

1. Check the [ChEMBL FAQ](https://chembl.gitbook.io/chembl-interface-documentation/frequently-asked-questions) for known data issues
2. Verify the ChEMBL API status at [www.ebi.ac.uk/chembl/api/status](https://www.ebi.ac.uk/chembl/api/utils/status)
3. Review the [ChEMBL Web Services documentation](https://chembl.gitbook.io/chembl-interface-documentation/web-services) for query syntax details

## Read next