Herodesks API er en offentlig REST API med Swagger-dokumentation.
Sådan finder du din API-nøgle
Hver Herodesk-konto har én API-nøgle.
Du kan finde den i din Herodesk-konto -> Indstillinger -> API & Webhooks:
Tryk på kopier-ikonet til højre for det forkortede forhåndsvisning af API-nøglen for at kopiere hele API-nøglen til dit udklipsholder.
API-dokumentation
Du kan finde Swagger API-dokumentationen her: https://api.herodesk.io
Paginering og anden metadata
Vores API returnerer de faktiske data fra din forespørgsel.
Detaljer om paginering og anden metadata findes i headerne.
Begrænsning af hastighed
Vores API bruger begrænsning af hastighed for at sikre fair brug og platformsstabilitet. Hastighedsbegrænsninger er baseret på dit Herodesk-abonnementsplan.
Hastighedsbegrænsninger efter plan
| Plan | Hastighedsbegrænsning |
|---|---|
| Herodesk Free | API ikke tilgængelig |
| Herodesk Basic | 60 forespørgsler/min |
| Herodesk Plus | 600 forespørgsler/min |
Disse hastighedsbegrænsninger gælder på tværs af alle endepunkter ved hjælp af en glidende vindues-algoritme, som sikrer en jævn og fair håndhævelse uanset hvornår i minuttet du foretager dine forespørgsler.
Vægtede forespørgselsomkostninger
Ikke alle API-opkald koster det samme. De fleste forespørgsler koster 1 point i forhold til din hastighedsbegrænsning, men nogle handlinger er dyrere:
| Handling | Omkostning |
|---|---|
| De fleste endepunkter (GET, osv.) | 1 |
| Opret samtale | 5 |
| Opret/send besked | 25 |
For eksempel, på Basic-planen (60/min), bruger afsendelse af en enkelt besked 100 points — hvilket overstiger den fulde tilladelse. Planlæg dit forbrug derefter, særligt for integrationer med mange beskeder, hvor Plus-planen anbefales.
404-straf
Forespørgsler, der resulterer i et 404 Not Found-svar, medfører en ekstra straf på 10 % af din hastighedsbegrænsning ud over den normale forespørgselsomkostning. Dette modvirker ugyldige forespørgsler og API-enumerering.
| Plan | 404-straf |
|---|---|
| Basic (60/min) | 6 ekstra points pr. 404 |
| Plus (600/min) | 60 ekstra points pr. 404 |
For eksempel, på Basic-planen, koster et 404-svar 1 (normal) + 6 (straf) = 7 points i alt.
Midlertidig blokering ved overdrevne 404'er
Hvis din integration genererer 50 eller flere 404-svar inden for 5 minutter, vil din API-nøgle blive midlertidigt blokeret i 15 minutter. I denne tid vil alle forespørgsler returnere 429 Too Many Requests.
Respons-header
Hver API-respons inkluderer header til at hjælpe dig med at overvåge dit forbrug af hastighedsbegrænsningen:
| Header | Beskrivelse |
|---|---|
| X-Rate-Limit-Remaining | Antal points tilbage i det aktuelle vindue |
| X-Rate-Limit-Reset | Sekunder indtil det aktuelle vindue nulstilles |
| X-Rate-Limit-Cost | Omkostningen ved den aktuelle forespørgsel |
| X-Rate-Limit-404-Penalty | Yderligere straf anvendt (kun på 404-svar) |
| X-Rate-Limit-Banned | true hvis din API-nøgle er midlertidigt blokeret |
| X-Rate-Limit-Ban-Reason | Årsag til blokeringen og hvornår den udløber |
| X-Rate-Limit-Ban-Expires | Sekunder indtil blokeringen ophæves |
Hvad sker der, når du overskrider grænsen
Hvis du overskrider din hastighedsbegrænsning, vil API'en returnere et 429 Too Many Requests-svar. Brug headeren X-Rate-Limit-Reset til at bestemme, hvornår du kan genoptage at foretage forespørgsler.
Bedste praksis
- Overvåg respons-headerne — brug X-Rate-Limit-Remaining til at dæmpe dine forespørgsler før du rammer grænsen.
- Håndter 429-svar elegant — implementer eksponentiel backoff og gentagelseslogik.
- Undgå ugyldige forespørgsler — 404-svar straffes, så valider ressourc-ID'er før du foretager API-opkald.
- Brug Plus-planen til integrationer med mange beskeder — afsendelse af beskeder koster 100 points pr. forespørgsel.
Disse hastighedsbegrænsninger gælder på tværs af alle endepunkter.