Reference — Images, Caching, Errors

Image CDN, cache TTLs, and error handling for V6

Image / Logo URLs

All logo / image fields in V6 responses are filenames, not full URLs. Prefix them with our image CDN host:

https://img.sportsapipro.com/{filename}

For thumbnails / list views, append !w80:

https://img.sportsapipro.com/92a6308394834fd38eadaf9105c99749.png!w80

Asset type	Example filename
Team logo	92a6308394834fd38eadaf9105c99749.png
Competition logo	da617cd58cd9cffaae0daec865457fb5.png
Player photo	fe8aec51afeb2de633c9a52e6d3b4c89.png
Bookmaker logo	Same as above

Caching Behavior

V6 ships an internal cache to absorb upstream rate limits. Every response includes a cacheHit: boolean flag.

Bucket	Endpoints	TTL
Live (5 s)	/team-stats, /commentary, /ball-by-ball	5 seconds
Near-live (30 s)	/odds, /odds/{companyId}, /predictions	30 seconds
Per-match (60 s)	/match/{id}, /match/{id}/incidents, /match/{id}/stats, /match/{id}/lineups, /match/{id}/h2h, /match/{id}/history, /match/{id}/tables, /match/{id}/scorecards	60 seconds
Reference (10 min)	Competitions, teams, players, transfers, world-cup endpoints	10 minutes
Static (1 hour)	/fifa/rankings, /rankings, /countries, /sports, /counts	1 hour

You can inspect the cache via:

GET /api/v1/cache/stats

Error Handling

V6 errors are always JSON, wrapped in { success: false, error: "..." }. Common cases:

HTTP	error body	Cause
401	{ "success": false, "error": "Unauthorized" }	Missing or invalid x-api-key
404	{ "success": false, "error": "Match not found" }	Match ID is wrong, expired, or from a different sport
429	{ "success": false, "error": "Rate limit exceeded" }	Your daily / per-minute quota tripped
5xx	{ "success": false, "error": "Upstream timeout" }	AiScore protobuf upstream was slow — retry with backoff

Key Differences vs. Other Versions

Capability	V1 (365scores)	V2 (Football-data)	V6 (AiScore)
Live scores	✅	✅	✅
Incidents with player IDs	Partial	✅	✅
Multi-bookmaker odds	❌	❌	✅ (3 formats)
3D animation widget	❌	❌	✅
Transfers (global)	❌	Partial	✅ (13.4k+ paginated)
FIFA rankings history	❌	❌	✅ (348 pubTimes)
World Cup archive 1930→	❌	Partial	✅
Esports stats	❌	❌	✅
Player salary + top earners	❌	❌	✅

Pick V6 when you need deep historical archives, multi-bookmaker odds, and AiScore-specific assets (animation widget, transfers feed, FIFA ranking timeline).