API-nycklar och rate limits

Så autentiserar du, hur quotas fungerar och hur auto-throttle skyddar källan.

Uppdaterad 2026-05-19

API-nyckelns format

Nycklar börjar med prefixet zk_ följt av 32 bytes URL-safe base64.

zk_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789-_

Skickas i header X-API-Key på varje anrop. Nyckeln visas endast en gång vid skapande — sparar du den inte, regenerera.

Tier-quotas (default)

Tier Per minut Per timme Per dygn Burst
free 30 500 5 000 10
starter 60 2 000 20 000 30
pro 200 10 000 100 000 100
enterprise obegränsat obegränsat obegränsat 500

Quotas styrs per användare och kan justeras manuellt av admin via /admin/users/{id}/policy.

Auto-throttle

Vid upprepad överträdelse aktiveras automatiska bannlysningar med stegvis ökande längd:

Level 1: 2 min
Level 2: 5 min
Level 3: 10 min
Level 4: 30 min
Level 5: 60 min

Nivån nollställs efter 12 timmar utan incident.

Globalt anonymt tak

Utöver per-user-limiten finns ett globalt cap på 100 anonyma sökningar/dygn över hela tjänsten. Detta skyddar mot DDoS och bot-skraping på /web/*-endpoints. Påverkar inte API-nyckelanrop.

Bästa praxis

  1. Cache-a på din sida — postnr-uppslag är effektivt cachebart i timmar/dagar.
  2. Använd batch-endpoints när de släpps (planerade).
  3. Hantera 429 med exponential backoff. Återkomma omedelbart triggar auto-throttle.
  4. Använd X-Request-ID-header i produktion för spårning.

Skapa nyckel

I dagsläget skapas nycklar av admin. Kontakta jonas@cnza.co så får du tier-rekommendation och en nyckel.

I framtiden (när airpipe-billing är klart) kommer självbetjäning via /auth/signup → billing-portal.