Snelheidslimieten en paginering in de MCP-server van Forktastic

Elke API heeft snelheidslimieten nodig. De Forktastic MCP-server dwingt 60 verzoeken per minuut en 5.000 verzoeken per dag per token af, met op offset gebaseerde paginering op lijsteindpunten. Dit is het referentiedocument — wat de limieten zijn, hoe ze zich gedragen wanneer ze worden overschreden, hoe paginering werkt en hoe agents ontworpen kunnen worden die binnen de perken blijven.

De cijfers

• 60 verzoeken per minuut per token. Bursting boven 60 in een schuifvenster van 60 seconden retourneert HTTP 429.
• 5.000 verzoeken per dag per token. Het dagelijkse venster is van middernacht UTC tot middernacht UTC. Overschrijding retourneert HTTP 429 totdat de bucket opnieuw wordt ingesteld.
• Per token, niet per account. Als je drie PAT's hebt, heb je 3 × 60/min en 3 × 5.000/dag.

Hoe een 429-reactie eruitziet

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": "rate_limited",
  "limit_type": "per_minute",
  "reset_in_seconds": 12
}

De Retry-After header vertelt je hoe lang je moet wachten. Voor limieten per minuut is dit meestal 0-60 seconden. Voor limieten per dag kan dit uren duren.

Paginering

Lijsteindpunten (search_recipes, list_cookbooks, search_cookbooks, get_trending) gebruiken op offset gebaseerde paginering:

• limit — items per pagina. Standaard 20, max. 100.
• offset — aantal over te slaan items. Standaard 0.

Om door de resultaten te bladeren, verhoogt u de offset met de limiet bij elke aanroep. Om alle items op te halen, blijft u pagineren totdat u een korte pagina krijgt (minder items dan de limiet), wat betekent dat u het einde hebt bereikt.

Het PGRST103 offset-overschrijdingsgedrag

Als je de offset voorbij het totale aantal instelt, retourneerden oudere versies van de API een HTTP 416-fout (PGRST103). Huidig gedrag: offset-overschrijding retourneert een lege array, geen fout. Dit zorgt ervoor dat pagineren-tot-leeg netjes werkt. Vertrouw niet op PGRST103-fouten als een signaal voor het einde van de lijst — gebruik de arraylengte.

Agentontwerppatronen die binnen de perken blijven

Cache indien mogelijk. Als uw agent elk uur dezelfde kookboeklijst leest, cache deze dan. De gegevens veranderen langzaam.

Batchgewijs lezen. Gebruik zoeken met een grotere limiet in plaats van te loopen met limit=1. Eén search_recipes-aanroep met limit=100 is één verzoek; 100 aanroepen met limit=1 zijn 100 verzoeken.

Respecteer Retry-After. Wanneer je een 429 raakt, wacht dan precies de tijd die de header aangeeft. Probeer niet agressief opnieuw — dat verergert de throttle alleen maar.

Spreid achtergrondtaken. Als uw wekelijkse maaltijdplanagent elke maandag om 8 uur 's ochtends draait, net als duizend andere mensen, bereikt u allemaal de snelheidslimiet. Voeg een kleine willekeurige jitter toe (±5 minuten) zodat de belasting zich verspreidt.

Gaan deze limieten veranderen?

Mogelijk naar boven, als gebruikspatronen dit rechtvaardigen. De huidige cijfers zijn conservatief voor een gloednieuwe MCP-server in productie. We beginnen liever strak en versoepelen dan los en moeten achteraf aanscherpen (wat elke agent breekt die vertrouwde op hogere limieten).

Wat gebeurt er als ik hogere limieten nodig heb?

Voorlopig: verdeel uw workload over meerdere PAT's (elk heeft zijn eigen bucket), of batch uw reads agressiever. Toekomst: we zullen waarschijnlijk op niveaus gebaseerde limieten aanbieden voor gebruikers met legitieme behoeften aan een hoger volume.

Waar ga je hierna naartoe?

Voor toolreferentie, 7 MCP-tools. Voor PAT-beheer, PAT-walkthrough. Voor Claude-setup, Claude-walkthrough. Voor de MCP-pijler, MCP-pijlergids.