Erros 4xx Comuns

Quatro erros de uso do lado do cliente respondem pela maioria das respostas 4xx/410 recorrentes da SharpAPI. Cada corpo de erro já nomeia a correção. Esta página as reúne em um só lugar para que você vá do código de status à correção sem abrir um ticket de suporte.

offset acima de 500 → 400 offset_too_largePermalink for this section

A paginação profunda com offset é limitada a 500 em /api/v1/odds e /api/v1/odds/delta. Uma varredura completa com ordenação custa o mesmo independentemente da profundidade do offset, então o limite evita cadeias de páginas caras.

{
  "error": {
    "code": "offset_too_large",
    "message": "offset must be <= 500; use cursor= from the previous response for deeper pagination",
    "max_offset": 500
  }
}

Correção: não pagine além de offset=500. Para alcançar mais linhas, ou

• passe o valor cursor= da resposta anterior de /odds (paginação keyset, sem limite de offset), ou
• restrinja a consulta para que cada conjunto de resultados caiba sob o limite: adicione league=, um filtro de data ou event=, ou um único market_type=.

Em /odds/delta, avance since= para o updated_at da resposta anterior em vez de aumentar o offset.

Caminhos de opportunities sem namespace → 410 GonePermalink for this section

Cada tipo de opportunity vive sob /api/v1/opportunities/. Os caminhos abreviados (/api/v1/ev, /api/v1/arbitrage, /api/v1/middles, /api/v1/low_hold) retornam 410 Gone e nomeiam o substituto:

{
  "error": {
    "code": "unknown_endpoint",
    "message": "There is no /api/v1/ev endpoint. Use GET /api/v1/opportunities/ev (Pro tier or higher).",
    "correct_endpoint": "/api/v1/opportunities/ev",
    "docs": "https://docs.sharpapi.io/api-reference"
  }
}

Correção: use o caminho com namespace de correct_endpoint.

Streaming na raiz da API → 400Permalink for this section

Streaming em tempo real não é servido pela raiz da API (https://api.sharpapi.io/). Uma requisição à raiz com intenção de streaming, ou seja com parâmetro channels=/channel= ou cabeçalho Upgrade de WebSocket, é respondida com um ponteiro para os endpoints reais em vez do redirect para a documentação que uma visita simples à raiz recebe:

{
  "error": {
    "code": "validation_error",
    "message": "Streaming is not available on the API root. Use Server-Sent Events at GET /api/v1/stream, or WebSocket at wss://ws.sharpapi.io — both require the WebSocket add-on. Channels: odds, opportunities, gamestate.",
    "stream_endpoints": {
      "sse": "https://api.sharpapi.io/api/v1/stream",
      "websocket": "wss://ws.sharpapi.io"
    },
    "docs": "https://docs.sharpapi.io/api-reference"
  }
}

Correção: escolha um transporte:

• Server-Sent Events: GET https://api.sharpapi.io/api/v1/stream, veja SSE Stream.
• WebSocket: wss://ws.sharpapi.io, veja WebSocket Stream.

Ambos exigem o add-on de WebSocket (ou um trial de streaming ativo / Enterprise).

Slug de filtro desconhecido → 400 invalid_filterPermalink for this section

?league=, ?sport=, ?sportsbook= e ?market= são validados contra o registro vivo. Um valor desconhecido retorna 400 invalid_filter em vez de casar silenciosamente com zero linhas, então um erro de digitação aparece como bug do cliente, não como “sem dados”. O corpo sempre aponta para o endpoint que lista os valores válidos e adiciona uma sugestão did_you_mean quando o valor está próximo de um slug real:

{
  "error": {
    "code": "invalid_filter",
    "message": "invalid filter values: league=[norway_2nd_div]; see GET /api/v1/leagues for valid values",
    "details": {
      "fields": { "league": ["norway_2nd_div"] },
      "reference": { "league": "/api/v1/leagues" },
      "did_you_mean": [
        { "field": "league", "value": "norway_2nd_div", "try": { "league": "norway_-_second_division" } }
      ]
    }
  }
}

Correção: busque o conjunto válido no endpoint de referência indicado em details.reference e filtre com um slug exato: