Ratenlimits und Fehler
Verfügbar inProResearch
Die API begrenzt, wie viele Anfragen ein Schlüssel und ein Konto stellen können, und beantwortet jede Ablehnung mit einem Statuscode und einem stabilen Fehlercode. Lies den Code, nicht den Nachrichtentext: Der Code ändert sich nicht.
Limits
Zwei Limits gelten für jeden Aufruf mit einem Schlüssel:
- Pro Schlüssel, pro Stunde. Jeder Schlüssel hat sein eigenes Stundenlimit, begrenzt auf das Maximum deines Tarifs.
- Pro Konto, pro Tag. Alle deine REST-Aufrufe teilen sich ein Tagesbudget. Der Tag ist UTC und wird um 00:00 UTC zurückgesetzt.
Die Zahlen für jeden Tarif stehen in der Tabelle unter Schlüssel, Scopes und Limits.
Einige Routen haben ein kurzes zusätzliches Limit pro Minute: Eine Frage stellen (POST /ask) und
einen Upload starten oder abschließen erlauben nur eine begrenzte Zahl von Aufrufen pro Minute.
Header
Jede Antwort auf einen Aufruf, der die Stundenprüfung bestanden hat, trägt:
X-RateLimit-Limit: das für diesen Schlüssel geltende Limit.X-RateLimit-Remaining: die in der aktuellen Stunde verbleibenden Aufrufe.
Wenn du über einem Limit bist, lautet die Antwort 429 mit Retry-After, der Anzahl der Sekunden,
die du warten sollst.
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
Retry-After: 1260
Höflich wiederholen
Warte Retry-After Sekunden und versuche es dann erneut. Wiederhole nicht sofort in einer Schleife.
Ein Skript, das viele Aufrufe macht, sollte stoppen, wenn das Tageslimit erreicht ist, und am nächsten
Tag weitermachen. Das Beispiel unter Beispiele zeigt eine Anfragefunktion, die das
tut.
GET /rest/v2/usage sagt dir, wie viel vom Tag du verbraucht hast.
Der Aufbau eines Fehlers
Jede Ablehnung nutzt dieselbe JSON-Form. success ist false, und error enthält die Details.
{
"success": false,
"error": {
"statusCode": 403,
"message": "This API key lacks the scope read:library.",
"code": "SCOPE_REQUIRED",
"details": { "scopes": ["read:library"] },
"timestamp": "2026-11-04T09:00:00.000Z",
"path": "/rest/v2/search",
"method": "GET"
}
}
code ist der maschinenlesbare Teil. Er kann bei einfachen Validierungs- oder Nicht-gefunden-Antworten
fehlen, wo statusCode und message die Bedeutung tragen. message kann eine Liste von Strings sein,
wenn mehrere Felder falsch sind.
Status- und Fehlercodes
| Status | Code | Bedeutung |
|---|---|---|
| 400 | - | Die Anfrage ist fehlerhaft. Ein Query-Parameter oder Body-Feld, das die Route nicht kennt, ist ebenfalls ein 400. |
| 400 | SCOPE_NOT_ALLOWED | Du hast beim Erstellen eines Schlüssels einen Scope angefordert, den dein Tarif nicht enthält. |
| 401 | API_KEY_INVALID | Der Schlüssel fehlt, ist unbekannt, widerrufen, abgelaufen oder gesperrt. Die Antwort trägt WWW-Authenticate: Bearer realm="readsira". |
| 401 | API_KEY_IN_QUERY | Der Schlüssel wurde in der Adresse gesendet. Sende ihn in einem Header. |
| 402 | PLAN_REQUIRED | Der Tarif hat keine REST-API (Free) oder keine Uploads. MCP-Schlüssel funktionieren weiterhin unter /mcp. |
| 402 | PLAN_LIMIT_REACHED | Ein Mengenlimit ist erreicht, zum Beispiel die Antworten pro Monat. |
| 402 | AI_QUOTA_EXCEEDED | Das KI-Budget dieses Monats ist aufgebraucht (POST /ask). |
| 402 | PROJECT_LIMIT_REACHED | Ein Projekt hat das Limit an Einträgen deines Tarifs erreicht. |
| 403 | SCOPE_REQUIRED | Dem Schlüssel fehlt der Scope, den die Route braucht. error.details.scopes nennt ihn. |
| 404 | - | Nicht gefunden oder nicht deins. Die API sagt nicht, was von beidem. |
| 409 | PROJECT_ARCHIVED | Du hast versucht, in ein archiviertes Projekt zu schreiben. |
| 429 | RATE_LIMITED | Das Stunden- oder Tageslimit. error.details hat window (hour oder day), limit und retryAfterSeconds. |
| 503 | AI_PAUSED | KI ist für den Tag pausiert (nur POST /ask). Die Suche funktioniert weiter. |
Ein 429 ohne Code kommt vom kurzen Minutenlimit einer Route. Warte und wiederhole auf dieselbe Weise.
Grenzen der Eingaben
Die API prüft jede Eingabe und lehnt die gesamte Anfrage mit 400 ab, wenn eine außerhalb des
Bereichs liegt.
| Route | Eingabe | Erlaubt |
|---|---|---|
GET /search | q | 1 bis 500 Zeichen |
GET /search | limit | 1 bis 20, Standard 8 |
POST /ask | question | 1 bis 2000 Zeichen |
POST /ask | bookmarkIds | 1 bis 50 IDs |
GET /documents/:id | offset | 0 oder mehr Zeichen |
GET /documents/:id | maxChars | 1 bis 20.000, Standard 12.000 |
GET /documents/:id/chunks | limit | 1 bis 100, Standard 20 |
GET /documents/:id/transcript | limit | 1 bis 500 |
GET /projects | limit | 1 bis 50, Standard 20 |
GET /projects/:id/context | q | 1 bis 500 Zeichen |
GET /projects/:id/context | maxChars | 1 bis 32.000, Standard 16.000 |
Jede Route hat eine vollständige Liste mit Typen in der REST-API-v2-Referenz.