Partner-API (B2B)
Errors & rate limits
Partner API error codes, per-key rate limits with X-RateLimit headers, and how to retry.
On this page
Error format#
Fehlerantworten haben die Form { statusCode, code, message }. message ist menschenlesbarer englischer Text und kann sich ändern – verzweige daher immer anhand von code.
// Success
{ "success": true, "data": ..., "total": 128, "page": 1, "limit": 20 }
// Error
{ "statusCode": 401, "code": "INVALID_API_KEY", "message": "The API key is invalid." }Hinweis
Error codes#
| HTTP | code | Bedeutung und Lösung |
|---|---|---|
| 401 | API_KEY_REQUIRED | Kein Schlüssel gesendet – füge den Header X-API-Key hinzu |
| 401 | INVALID_API_KEY | Fehlerhafter oder unbekannter Schlüssel – prüfe, ob er beim Kopieren nicht abgeschnitten wurde und kein Public-API-Schlüssel ist |
| 401 | KEY_REVOKED | Widerrufener Schlüssel – stelle einen neuen aus |
| 401 | KEY_EXPIRED | Abgelaufener Schlüssel (auch ein alter Schlüssel nach Ablauf der Rotations-Übergangsfrist) – verwende den neuen Schlüssel |
| 403 | PARTNER_SUSPENDED | Konto ist nicht aktiv – kontaktiere esimoa |
| 403 | INSUFFICIENT_SCOPE | Anfrage außerhalb der Schlüsselberechtigungen |
| 403 | IP_NOT_ALLOWED | Aufruf von einer IP außerhalb der Allowlist – füge die ausgehende IP deines Servers hinzu |
| 404 | PRODUCT_NOT_FOUND | Unbekanntes oder eingestelltes Produkt |
| 429 | RATE_LIMITED | Ratenlimit überschritten – nach den in Retry-After angegebenen Sekunden erneut versuchen |
Rate limits#
Hinweis
B2B-API-Anfragen sind standardmäßig auf 20,000 pro Stunde und Schlüssel begrenzt.
Das 3,600-Sekunden-Fenster beginnt mit der ersten Anfrage; das Minutenlimit gilt zusätzlich. Kontingente zählen Aufrufe, nicht übertragene MB. Betriebliche Einstellungen können das Kontingent ändern.
X-RateLimit-Hour-Limit · X-RateLimit-Hour-Remaining · X-RateLimit-Hour-Reset
Diese Header melden das Stundenlimit, die verbleibenden Aufrufe und die Rücksetzzeit (Unix-Sekunden). Ist das Stundenlimit erschöpft, wird HTTP 429 mit Retry-After in Sekunden zurückgegeben. Vom Minutenlimit abgelehnte Aufrufe zählen nicht zum Stundenkontingent.
Standard sind 300 Anfragen pro Minute und Schlüssel (pro 60-Sekunden-Fenster, über alle Server geteilt). esimoa kann das Limit pro Konto gemäß deinem Vertrag erhöhen. Jede authentifizierte Antwort enthält Kontingent-Header.
X-RateLimit-Limit— erlaubte Anfragen pro MinuteX-RateLimit-Remaining— verbleibende Anfragen im aktuellen ZeitfensterX-RateLimit-Reset— Zeitpunkt des Zurücksetzens (Unix-Sekunden)Retry-After— bei 429 die Wartezeit in Sekunden bis zum nächsten Versuch
HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1790000000
HTTP/1.1 429 Too Many Requests
Retry-After: 18
{ "statusCode": 429, "code": "RATE_LIMITED", "message": "Rate limit exceeded (300 requests per minute)." }Retrying#
- Bei 429 warte die in Retry-After angegebenen Sekunden ab und versuche es dann erneut.
- Wiederhole 5xx-Fehler einige Male mit exponentiellem Backoff.
- 400, 401, 403 und 404 ändern sich bei Wiederholung nicht – behebe die Ursache.
- Wenn du den Katalog ein paar Minuten zwischenspeicherst, bleibst du deutlich unter dem Limit.
async function b2bFetch(url, attempt = 0) {
const res = await fetch(url, { headers: { 'X-API-Key': process.env.ESIMOA_PARTNER_KEY } });
if (res.status === 429 && attempt < 3) {
const wait = Number(res.headers.get('Retry-After') ?? 1);
await new Promise((r) => setTimeout(r, wait * 1000));
return b2bFetch(url, attempt + 1);
}
const body = await res.json();
if (!res.ok) throw Object.assign(new Error(body.message), { code: body.code, status: res.status });
return body;
}