Best Practices and Common Mistakes

Recommended patterns and mistakes to avoid when working with the SockOdds API.

Patterns to follow

Set up a server-side process to sync data from the API into your database

• The most secure and scalable way to ingest API data — a cron job every 2–5 minutes handles it.
• You control how up-to-date your data is, and 10× more app traffic doesn't mean 10× more API calls.

Calculate your expected usage

• How many leagues you track, how often you refresh, and how many events per league at a time.
• Only events with open markets? Then oddsAvailable=true and count those.

Specify oddID when you only need specific markets

• Cuts payloads by up to ~100× and improves response times.

Implement retry logic on 500-level errors

• Wait a short period, retry once. If it still fails, stop and log.

Use query params to filter data

• Filtering at the API level means less irrelevant data returned, faster responses, fewer objects.

Use eventID by itself for direct lookups

• With eventID or eventIDs all other filters are ignored; response-shaping params (oddID, bookmakerID, includeAltLines) still apply.

Use limit and cursor together

• Raise limit before you start paging.

Keep your API key secure

• Never in frontend code. Never in version control.

Monitor your usage

• /account/usage shows where you stand against your limits.

Handle missing fields defensively

• Critical fields (eventID, sportID, leagueID) are always present; less critical ones (colors, results, players) may be empty. Use names.long || names.medium || names.short.

Read the honesty flags

• available, info.stale and notice tell you what the feed knows and what your plan withheld. Treat them as data.

Vary your polling intervals

• Odds far from kick-off change slowly and many markets aren't offered until 24–48 hours out. Poll less for the far future.

Learn the oddID structure

• {statID}-{statEntityID}-{periodID}-{betTypeID}-{sideID}. Knowing it makes everything faster.

Look league keys up, never construct them

• RUGBYLEAGUE_NRLW, FR_LIGUE_1, UCL — from /leagues.

Anti-patterns to avoid

Making API requests from a frontend/browser

• Exposes your key. Proxy through a backend, or sync to your database and query that.

Polling on an interval on the free plan

• 10 requests a minute goes quickly; run requests manually and upgrade when you're ready to schedule.

Polling too frequently

• The source refreshes every ~2 minutes; faster polling wastes quota.

Always polling all upcoming games

• Cache longer for far-off games.

Not considering response codes

• A 429 carries Retry-After; not waiting burns quota faster.

Not considering error messages

• Every error has success: false and an error field. Log it.

Always including includeAltLines=true

• Multiplies the payload; ask only when needed.

Using startsAfter/startsBefore when unneeded

• They widen the scan; combine with as few other filters as possible.

Filtering results on the client

• Filter at the API with query parameters instead of downloading everything.

Using wrong/invalid query parameters

• See the reference for valid parameters per endpoint.

Acting on a stale or suspended price

• Verify on the book via links.bookmakers before staking; prices move.