PubChem troubleshooting

This page helps you diagnose the common problems with a 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, fields, and structure search.

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.
• 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.

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