---
title: PubChem troubleshooting
description: 'Fix empty PubChem results, synonyms that map to several compounds, structure uploads over 10 MB, and throttling at 5 requests per second or 400 per minute.'
tags:
  - pubchem
  - troubleshooting
---

This page helps you diagnose the common problems with a [PubChem](/docs/pubchem) search — empty results, ambiguous synonyms, failed structure-file uploads, and rate limiting — along with data-quality and performance checks to run before a bulk export. For how to build queries and pick fields, see [search](/docs/pubchem/search), [fields](/docs/pubchem/fields), and [structure search](/docs/pubchem/structure).

## Common errors

- **Empty results**: verify the identifier (CID/InChIKey) and consider switching from synonym to identifier search — a name that fails to resolve returns nothing.
- **Ambiguous synonyms**: a common name can map to several compounds; narrow with property filters or switch to an InChIKey or CID for an exact match.
- **Structure search failed**: check that the SMILES or SMARTS string parses. Structure searches take a SMILES, SMARTS, InChIKey, CID or name, not a structure file directly; if you have an SDF or mol file, upload it and ask Ivy to read the structures from it first. See [structure search](/docs/pubchem/structure).
- **Rate limited**: PubChem's PUG REST API throttles heavy usage.

## Rate limits and pacing

The platform caches and queues requests to respect PubChem's published PUG REST limits, but a large bulk pull can still hit them:

- No more than **5 requests per second**.
- No more than **400 requests per minute**.
- No more than **300 seconds of running time per minute**.

If you see throttling, retry with exponential backoff, lean on cached results, and chunk large jobs rather than requesting everything at once. See [rate limits](/docs/pubchem/rate-limits).

## Data quality checks

- Compare returned CID/InChIKey values to your source list to ensure correct mapping.
- Spot-check a few records for property completeness before a bulk export.
- If properties are missing, it is usually a PubChem coverage gap (older entries lack some modern calculated properties) rather than an error.

## Performance

- Paginate large result sets instead of requesting everything at once.
- Reuse cached results when possible; refresh only when you need the newest data.

If issues persist, include the query type (text/identifier/structure), the filters used, and whether the request came from cached results when contacting support.

## Read next