Häufige 4xx-Fehler

Vier clientseitige Nutzungsfehler verursachen die meisten wiederkehrenden 4xx/410-Antworten von SharpAPI. Jeder Error-Body benennt die Korrektur bereits selbst. Diese Seite sammelt alle vier an einem Ort, damit Sie einen Statuscode der passenden Korrektur zuordnen können, ohne ein Support-Ticket zu öffnen.

offset über 500 → 400 offset_too_largePermalink for this section

Tiefe Paginierung mit offset ist auf /api/v1/odds und /api/v1/odds/delta auf 500 begrenzt. Ein vollständiger Scan mit Sortierung kostet unabhängig von der Offset-Tiefe gleich viel, das Limit verhindert also teure Seitenketten.

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

Korrektur: Paginieren Sie nicht über offset=500 hinaus. Um weitere Zeilen zu erreichen, entweder

• den cursor=-Wert aus der vorherigen /odds-Antwort übergeben (Keyset-Paginierung, ohne Offset-Limit), oder
• die Anfrage so eingrenzen, dass jede Ergebnismenge unter das Limit passt: league=, einen Datums- oder event=-Filter oder ein einzelnes market_type= ergänzen.

Auf /odds/delta setzen Sie since= auf das updated_at der vorherigen Antwort, statt offset zu erhöhen.

Opportunity-Pfade ohne Namespace → 410 GonePermalink for this section

Jeder Opportunity-Typ liegt unter /api/v1/opportunities/. Die verkürzten Pfade (/api/v1/ev, /api/v1/arbitrage, /api/v1/middles, /api/v1/low_hold) geben 410 Gone zurück und benennen ihren Ersatz:

{
  "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"
  }
}

Korrektur: Verwenden Sie den Namespace-Pfad aus correct_endpoint.

Streaming auf der API-Root → 400Permalink for this section

Echtzeit-Streaming wird nicht von der API-Root (https://api.sharpapi.io/) ausgeliefert. Eine Root-Anfrage mit Streaming-Absicht, also mit channels=/channel=-Query-Parameter oder WebSocket-Upgrade-Header, erhält einen Verweis auf die echten Endpoints statt des Docs-Redirects, den ein einfacher Root-Aufruf bekommt:

{
  "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"
  }
}

Korrektur: Wählen Sie einen Transport:

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

Beide erfordern das WebSocket-Add-on (oder einen aktiven Streaming-Trial bzw. Enterprise).

Unbekannter Filter-Slug → 400 invalid_filterPermalink for this section

?league=, ?sport=, ?sportsbook= und ?market= werden gegen die Live-Registry validiert. Ein unbekannter Wert gibt 400 invalid_filter zurück, statt stillschweigend null Zeilen zu treffen. Ein Tippfehler zeigt sich damit als Client-Bug, nicht als “keine Daten”. Der Body verweist immer auf den Endpoint mit den gültigen Werten und ergänzt einen did_you_mean-Vorschlag, wenn der Wert nahe an einem echten Slug liegt:

{
  "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" } }
      ]
    }
  }
}

Korrektur: Holen Sie die gültige Menge vom Referenz-Endpoint aus details.reference und filtern Sie mit einem exakten Slug: