# Handle API errors and limits

> Retry temporary failures without retrying an exhausted account. Respect Retry-After on minute limits. Monthly quota exhaustion needs reset or an approved u Underdog API (https://underdogapi.com) is an independent Underdog Fantasy pick'em data API: Higher/Lower lines with separate payout multipliers per side, line history, changes and graded results as JSON, CSV, MCP and streams.

Canonical page: https://underdogapi.com/underdog-api-errors-rate-limits

## Free offer

**Free API key, no card: 100 credits a month** on the live board, every league, separate Higher/Lower prices, and the last 24 hours of line history. Sign up: https://underdogapi.com/sign-up?ref=ai-claudebot

## Quickstart

1. Get a free key at https://underdogapi.com/sign-up?ref=ai-claudebot (no card), or let your agent request one: `POST https://underdogapi.com/api/v1/agent/signup` with `data_wanted` and `use_case`, then show your user the returned approval_url.
2. Export it: `export UNDERDOG_API_KEY=ud_...`
3. First call with curl:

```bash
curl --fail-with-body 'https://underdogapi.com/api/v1/projections?league=NBA&view=compact&limit=5' \
  -H "Authorization: Bearer $UNDERDOG_API_KEY" \
  -H 'X-User-Request: NBA dashboard integration check'
```

4. Same call in Python:

```python
import os, requests

r = requests.get(
    "https://underdogapi.com/api/v1/projections",
    params={"league": "NBA", "view": "compact", "limit": 5},
    headers={"Authorization": f"Bearer {os.environ['UNDERDOG_API_KEY']}"},
)
r.raise_for_status()
for line in r.json()["data"]:
    print(line["player"]["name"], line["market"]["stat"], line["line"])
```

## Use it from Claude (MCP)

Claude Code, one command:

```bash
claude mcp add --transport http underdog https://underdogapi.com/api/mcp --header "Authorization: Bearer $UNDERDOG_API_KEY"
```

Or add this server to your Claude MCP configuration (the key stays in the environment):

```json
{
  "mcpServers": {
    "underdog": {
      "type": "http",
      "url": "https://underdogapi.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${UNDERDOG_API_KEY}"
      }
    }
  }
}
```

Guide: https://underdogapi.com/use-with-claude

## Pricing

| Plan | Price | Credits / month | Notes |
| --- | --- | --- | --- |
| Free | $0 | 100 | No card. Live feed 5 minutes behind; last 24 hours of line history |
| Developer | $49/month | 10,000 | For models that need full training pages and loaded game-log seasons. Live feed, no added plan delay |
| Production | $149/month | 50,000 | For apps with real users and push delivery. Everything in Developer, signed webhooks for every change |
| Scale | $499/month | 250,000 | For apps whose traffic has outgrown Production. Everything in Production, 15 live-feed connections at once |

Full pricing: https://underdogapi.com/pricing

## On this page

For developers who need to handle api errors and limits.

Retry temporary failures without retrying an exhausted account.

[Get free API key](https://underdogapi.com/sign-up) [API reference](https://underdogapi.com/docs)

## Not for

Entry placement or fantasy-account support

This independent data service does not operate a fantasy account.

Guaranteed outcomes

Observations support research; they do not predict a winning entry.

## Leagues on the board now

Live

| League | Current offers | Markets | Last observed |
| --- | --- | --- | --- |
| BKFC | 0 | 3 | Nov 6, 23:15 UTC |
| CBB | 115 | 12 | Nov 15, 20:21 UTC |
| CFB | 0 | 35 | Nov 15, 18:02 UTC |
| CFL | 16 | 5 | Nov 15, 20:21 UTC |
| CS | 18 | 4 | Nov 15, 20:21 UTC |
| DOTA | 16 | 2 | Nov 15, 20:21 UTC |
| FIFA | 0 | 10 | Nov 8, 19:58 UTC |
| INTLBASKETBALL | 0 | 5 | Nov 13, 14:22 UTC |
| KBO | 0 | 3 | Nov 8, 00:09 UTC |
| LOL | 0 | 6 | Nov 14, 21:56 UTC |
| MMA | 0 | 13 | Nov 14, 22:50 UTC |
| MOTORSPORTS | 0 | 2 | Nov 8, 10:43 UTC |
| NBA | 1,007 | 24 | Nov 15, 20:21 UTC |
| NFL | 1,615 | 52 | Nov 15, 20:21 UTC |
| NHL | 837 | 15 | Nov 15, 20:21 UTC |
| OUTLAWS | 0 | 1 | Nov 7, 16:58 UTC |
| PGA | 0 | 2 | Nov 15, 13:02 UTC |
| TENNIS | 504 | 12 | Nov 15, 20:21 UTC |

Counts are offers on the latest board for each league. [Live status by league](https://underdogapi.com/status)

## Start with the data contract

Respect Retry-After on minute limits. Monthly quota exhaustion needs reset or an approved upgrade; never retry it in a tight loop.

## Bound retries by error class

Do not retry invalid credentials or malformed queries unchanged. Retry temporary failures with a cap, and respect Retry-After without allowing concurrent callers to stampede.

## Run a bounded integration example

Keep the bearer token in a server environment. Snippets that refer to an existing page, rows or url are processing examples to apply after a successful response; replace any market or cutoff placeholder deliberately.

```
const response = await fetch(url, { headers: { Authorization: "Bearer " + process.env.UNDERDOG_API_KEY } });
if (!response.ok) {
  const body = await response.json();
  const code = body.error?.code;
  if (code === "MONTHLY_QUOTA_EXCEEDED") throw new Error("Wait for reset or request an approved upgrade");
  if (response.status === 429) console.log("Minute limit; Retry-After:", response.headers.get("retry-after"));
  throw new Error(`HTTP ${response.status}: ${code}`);
}
```

## Verify the response and its limits

- Test invalid credentials and unavailable source data.
- Keep cursors, source status and timestamps with retained rows.
- Use coverage to confirm the requested sport and retained date window.

## Continue with the reference

Use the documented coverage contract for exact parameters and null meanings. A fictional demo validates a parser; it does not validate live collection or historical completeness.

## Try it

[**Run a bounded demo** Inspect fictional rows without a key.](https://underdogapi.com/playground) [**Download the starter kit** Guarded clients, samples and Postman requests.](https://underdogapi.com/developers/starter-kit)

Endpoint docs: [GET /api/v1/coverage](https://underdogapi.com/docs#coverage) [Plans and limits](https://underdogapi.com/pricing)

## Frequently asked questions

What is the main data constraint when I handle api errors and limits?

Respect Retry-After on minute limits. Monthly quota exhaustion needs reset or an approved upgrade; never retry it in a tight loop.

Should I retry a monthly quota error every minute?

No. Monthly exhaustion persists until reset or an approved plan change. Preserve the server’s code and reset time, and ask the account owner before purchasing an upgrade.

## Continue building

[Guide **API reference**](https://underdogapi.com/docs) [operations **Check observation freshness**](https://underdogapi.com/underdog-api-data-freshness) [beginner **Evaluate an Underdog data API**](https://underdogapi.com/underdog-api-alternatives)

[All developer resources](https://underdogapi.com/resources) [Pricing](https://underdogapi.com/pricing)

## References

- [Underdog API reference](https://underdogapi.com/docs)
- [OpenAPI contract](https://underdogapi.com/openapi.json)

On this page

[Not for](https://underdogapi.com/underdog-api-errors-rate-limits#not-for) [Start with the data contract](https://underdogapi.com/underdog-api-errors-rate-limits#start-with-the-data-contract-0) [Bound retries by error class](https://underdogapi.com/underdog-api-errors-rate-limits#bound-retries-by-error-class-2) [Run a bounded integration example](https://underdogapi.com/underdog-api-errors-rate-limits#run-a-bounded-integration-example-4) [Verify the response and its limits](https://underdogapi.com/underdog-api-errors-rate-limits#verify-the-response-and-its-limits-7) [Continue with the reference](https://underdogapi.com/underdog-api-errors-rate-limits#continue-with-the-reference-9) [FAQ](https://underdogapi.com/underdog-api-errors-rate-limits#faq)

[Playground](https://underdogapi.com/playground) [Plans and limits](https://underdogapi.com/pricing)

## FAQ

### Is there a free Underdog API?

Yes. The Free plan is a real API key on the live board, not a sample: 100 credits a month, every league, separate Higher/Lower prices and the last 24 hours of line history. No card is needed.

### Is this the official Underdog Fantasy API?

No. Underdog API is an independent data service. It is not affiliated with, endorsed by or sponsored by Underdog Fantasy or Underdog Sports.

### What data does it return?

Underdog Higher/Lower lines with separate payout multipliers and availability for each side, stable market ids through line moves, alternate rungs, recorded line history, changes, graded results and coverage/status endpoints.

### How do I use it from Claude or another AI agent?

Connect the MCP server at https://underdogapi.com/api/mcp with a bearer key, or call the REST API. Agents can request a key for their user with POST /api/v1/agent/signup.

### How much does it cost after the free tier?

Developer is $49/month for 10,000 credits, Production $149/month for 50,000, Scale $499/month for 250,000. Errors and unchanged 304 responses cost zero credits.

### How fresh is the data?

Each row carries its observation time. Check /api/v1/status and /api/v1/coverage before relying on a sport or window; missing collection is reported as unavailable, never filled in.

### Does it place entries or give picks?

No. It is data only: no entries, account operations, guaranteed outcomes or betting advice.

---
Independent data service, not affiliated with Underdog Fantasy or Underdog Sports. Docs: https://underdogapi.com/docs · OpenAPI: https://underdogapi.com/openapi.json · llms.txt: https://underdogapi.com/llms.txt
