API rate limits

De 5 niveaus

Elk verzoek passeert vijf poorten. De eerste die weigert, wint.

Dagelijkse caps per endpoint

Sommige endpoints hebben strengere limieten omdat ze aanzienlijke CPU- of GPU-tijd verbruiken:

Bestandsgroottelimiet

• 200 MB per bestand voor de API (tegenover 100 MB op de website).
• Sommige zware AI-tools hebben lagere interne limieten — bijvoorbeeld upscale-image is beperkt tot 20 MB om GPU-runs onder de 2 minuten te houden.

Headers op elk antwoord

Elk succesvol API-antwoord bevat de volgende headers zodat je je quota kunt volgen zonder /api/v1/limits te pollen:

X-RateLimit-Limit-Day: 1000
X-RateLimit-Remaining-Day: 873
X-RateLimit-Reset-Day: 1775865600     # unix timestamp
X-RateLimit-Limit-Hour: 150
X-RateLimit-Remaining-Hour: 142
X-RateLimit-Limit-Endpoint: 50
X-RateLimit-Remaining-Endpoint: 38

Wat gebeurt er als je een limiet bereikt

De API retourneert 429 Too Many Requests met een Retry-After-header (in seconden) en een X-RateLimit-Reason-header die aangeeft welk niveau is geraakt:

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Reason: cooldown

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded (cooldown). Retry after 1 seconds.",
    "details": { "reason": "cooldown", "retry_after": 1 }
  }
}

Mogelijke X-RateLimit-Reason-waarden: cooldown, burst, hourly, daily, endpoint:<name>, banned.

Ban-escalatie

Herhaald misbruik activeert een tijdelijke ban. Concreet: 10 rate-limit-weigeringen binnen 1 uur vanaf hetzelfde IP → ban van 24 uur met HTTP 403 Forbidden en error.code: BANNED.

Denk je dat je onterecht bent geband (bijvoorbeeld omdat je een IP deelt met veel gebruikers), neem dan contact op via /contact en we bekijken het.

Best practices om throttling te vermijden

• Wacht minstens 1 seconde tussen opeenvolgende verzoeken (of gebruik de Retry-After-header bij 429's).
• Gebruik batch-endpoints voor bulkwerk: POST /api/v1/batch verwerkt tot 20 bestanden in één HTTP-aanroep (elk bestand telt nog steeds mee voor je dagelijkse quota, maar je bespaart round trips).
• Let op de headers: zodra X-RateLimit-Remaining-Day onder 100 zakt, vertraag dan of cache je resultaten.
• Inspecteer je gebruik op elk moment met GET /api/v1/limits — dit endpoint telt NIET mee voor je quota.
• Probeer niet direct opnieuw bij een 429 — respecteer Retry-After. Directe retries kunnen ban-escalatie triggeren.

Hogere limieten nodig?

De huidige limieten zijn MVP-standaardwaarden. We houden het werkelijke gebruik in de gaten en passen ze aan op basis van vraag. Heb je een legitieme use case die hogere quota nodig heeft, neem dan contact op via /contact.

Een toekomstig betaald abonnement kan dedicated quota, priority queues en langere bestandsretentie bieden — maar de gratis variant blijft altijd bestaan.