> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sportsapipro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```text theme={null}
https://img.sportsapipro.com/{filename}
```

For thumbnails / list views, append `!w80`:

```text theme={null}
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:

```text theme={null}
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).