Cause: Invalid collection slug or collection delisted
Solution: Verify slug on OpenSea; try contract address instead
OpenSea Rate Limited
Error: 429 Too Many Requests
Cause: Exceeded API rate limits (4 req/sec without key)
Solution: Add OPENSEA_API_KEY; wait and retry; use cached data
OpenSea API Key Invalid
Error: 401 Unauthorized
Cause: Missing or invalid API key
Solution: Set OPENSEA_API_KEY environment variable; regenerate key
Alchemy API Error
Error: 403 Forbidden or invalid response
Cause: Missing or invalid Alchemy API key
Solution: Set ALCHEMY_API_KEY; check key permissions
IPFS Errors
IPFS Gateway Timeout
Error: Request timeout fetching metadata
Cause: IPFS gateway slow or content unavailable
Solution: Automatic fallback to alternate gateways
Invalid IPFS Hash
Error: Malformed IPFS URL or hash
Cause: Corrupted metadata in contract
Solution: Try fetching from OpenSea API instead
Metadata Not JSON
Error: Failed to parse metadata
Cause: Non-standard or corrupted metadata format
Solution: Token skipped from analysis
Data Errors
No Tokens Found
Error: Empty token list
Cause: Collection too new, unlaunched, or hidden
Solution: Wait for collection to be indexed; verify slug
Missing Attributes
Error: Token has no traits
Cause: Revealed/unrevealed state or non-standard format
Solution: Treated as all "None" traits
Token ID Not Found
Error: Requested token not in fetched data
Cause: Token ID outside fetched range or doesn't exist
Solution: Increase --limit to fetch more tokens
Cache Errors
Cache Read Failed
Error: JSONDecodeError on cache load
Cause: Corrupted cache file
Solution: Clear cache with cache --clear
Cache Directory Permission
Error: Cannot write to ~/.nft_cache
Cause: Permission issues
Solution: Check directory permissions; use different cache path
Algorithm Errors
Division by Zero
Error: Cannot calculate rarity
Cause: Trait frequency is 0 (shouldn't happen)
Solution: Uses minimum frequency of 1/total_supply
No Traits to Analyze
Error: Empty trait map
Cause: No valid attributes in metadata
Solution: Check metadata format; verify collection support
Environment Variables
Variable
Purpose
Default
OPENSEA_API_KEY
OpenSea API authentication
None (rate limited)
ALCHEMY_API_KEY
Alchemy NFT API
None (limited features)
Fallback Chain
1. OpenSea API → Primary source
↓ fails
2. Alchemy API → Backup metadata
↓ fails
3. Direct IPFS → Raw metadata fetch
↓ fails
4. Cache → Last known data
↓ fails
5. Error → User notification
Common Fixes
Slow analysis: Reduce --limit; use cached data
Incomplete data: Increase --limit
Wrong rankings: Verify algorithm choice; check for unrevealed tokens
API errors: Set API keys; check rate limits
1---2name: 2036-errors-a8257e283description: Error Handling Reference4---5# Error Handling Reference67## API Errors89**Collection Not Found**10- Error: `404 Not Found` or empty response11- Cause: Invalid collection slug or collection delisted12- Solution: Verify slug on OpenSea; try contract address instead1314**OpenSea Rate Limited**15- Error: `429 Too Many Requests`16- Cause: Exceeded API rate limits (4 req/sec without key)17- Solution: Add `OPENSEA_API_KEY`; wait and retry; use cached data1819**OpenSea API Key Invalid**20- Error: `401 Unauthorized`21- Cause: Missing or invalid API key22- Solution: Set `OPENSEA_API_KEY` environment variable; regenerate key2324**Alchemy API Error**25- Error: `403 Forbidden` or invalid response26- Cause: Missing or invalid Alchemy API key27- Solution: Set `ALCHEMY_API_KEY`; check key permissions2829## IPFS Errors3031**IPFS Gateway Timeout**32- Error: Request timeout fetching metadata33- Cause: IPFS gateway slow or content unavailable34- Solution: Automatic fallback to alternate gateways3536**Invalid IPFS Hash**37- Error: Malformed IPFS URL or hash38- Cause: Corrupted metadata in contract39- Solution: Try fetching from OpenSea API instead4041**Metadata Not JSON**42- Error: Failed to parse metadata43- Cause: Non-standard or corrupted metadata format44- Solution: Token skipped from analysis4546## Data Errors4748**No Tokens Found**49- Error: Empty token list50- Cause: Collection too new, unlaunched, or hidden51- Solution: Wait for collection to be indexed; verify slug5253**Missing Attributes**54- Error: Token has no traits55- Cause: Revealed/unrevealed state or non-standard format56- Solution: Treated as all "None" traits5758**Token ID Not Found**59- Error: Requested token not in fetched data60- Cause: Token ID outside fetched range or doesn't exist61- Solution: Increase `--limit` to fetch more tokens6263## Cache Errors6465**Cache Read Failed**66- Error: JSONDecodeError on cache load67- Cause: Corrupted cache file68- Solution: Clear cache with `cache --clear`6970**Cache Directory Permission**71- Error: Cannot write to ~/.nft_cache72- Cause: Permission issues73- Solution: Check directory permissions; use different cache path7475## Algorithm Errors7677**Division by Zero**78- Error: Cannot calculate rarity79- Cause: Trait frequency is 0 (shouldn't happen)80- Solution: Uses minimum frequency of 1/total_supply8182**No Traits to Analyze**83- Error: Empty trait map84- Cause: No valid attributes in metadata85- Solution: Check metadata format; verify collection support8687## Environment Variables8889| Variable | Purpose | Default |90|----------|---------|---------|91| `OPENSEA_API_KEY` | OpenSea API authentication | None (rate limited) |92| `ALCHEMY_API_KEY` | Alchemy NFT API | None (limited features) |9394## Fallback Chain9596```971. OpenSea API → Primary source98 ↓ fails992. Alchemy API → Backup metadata100 ↓ fails1013. Direct IPFS → Raw metadata fetch102 ↓ fails1034. Cache → Last known data104 ↓ fails1055. Error → User notification106```107108## Common Fixes1091101. **Slow analysis**: Reduce `--limit`; use cached data1112. **Incomplete data**: Increase `--limit`1123. **Wrong rankings**: Verify algorithm choice; check for unrevealed tokens1134. **API errors**: Set API keys; check rate limits
Run npx skillmds@latest add tools-only/2036-errors-a8257e28 in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Error Handling Reference It is listed under Research & Search on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
tools-only (@tools-only) published this skill. Their other Agent Skills are listed on their SkillMD profile.
tools-only