Fehler & Rate Limits

Die öffentliche Armox-API verwendet standardmäßige HTTP-Statuscodes und ein einheitliches JSON-Fehlerformat.

Fehlerantwort-Format

{ "error": "Human-readable message" }

Beispiele:

{ "error": "Invalid API key" }

{ "error": "Insufficient credits. Required 1000, available 200" }

Fehlercodes

Code	Bedeutung	Typische Ursache
`400`	Bad Request	Ungültiger Payload, fehlendes Pflichtfeld, ungültiges Modell
`401`	Unauthorized	Fehlender oder ungültiger Bearer-API-Schlüssel
`402`	Payment Required	Unzureichende Credits
`403`	Forbidden	Plan-/Zugangsbeschränkungen
`404`	Not Found	Ressource/Job/App nicht gefunden
`409`	Conflict	Job kann im aktuellen Status nicht storniert werden
`429`	Too Many Requests	Schlüsselbasiertes Rate Limit überschritten
`500`	Internal Server Error	Unerwarteter Backend-Fehler

Rate Limits

Rate Limiting wird pro API-Schlüssel mit einem rollierenden 60-Sekunden-Fenster durchgesetzt.

Jede erfolgreiche authentifizierte Antwort enthält:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

Wenn das Limit überschritten wird, gibt die API zurück:

Status 429
Fehler-Body { "error": "Rate limit exceeded" }
Retry-After: 60-Header

Umgang mit 429-Antworten

Empfohlene Strategie:

Retry-After-Header auslesen
Vor dem erneuten Versuch warten
Exponentielles Backoff mit Jitter bei wiederholten 429-Antworten verwenden
Synchronisierte Wiederholungsversuche über Worker hinweg vermeiden

JavaScript Retry-Beispiel

async function requestWithRetry(url, options, retries = 3) {
  for (let attempt = 0; attempt <= retries; attempt += 1) {
    const response = await fetch(url, options);
    if (response.status !== 429) return response;

    const retryAfter = Number(response.headers.get("Retry-After") || 2);
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
  }

  throw new Error("Exceeded retry attempts");
}

Credits und Abrechnungsverhalten

Credits werden bei Annahme einer Ausführung belastet
Fehlgeschlagene Jobs werden durch den Ausführungsablauf erstattet
Nutzung überwachen über GET /api/v1/account

Häufige Produktionsfehler

Invalid API key: falscher/abgelaufener/widerrufener Schlüssel
Public API access requires ...: Abonnement nicht berechtigt
Insufficient credits ...: Credits aufladen oder Ausführungskosten reduzieren
Rate limit exceeded: Backoff + Warteschlange hinzufügen

Debugging-Checkliste

Überprüfen, ob Authorization: Bearer ... vorhanden ist
Endpunkt-Pfad und Methode überprüfen
Request-IDs/Job-IDs in Ihrer App protokollieren
Response-Header für Rate-Limit-Beobachtbarkeit erfassen
Fehlgeschlagene Payloads für erneute Verarbeitung speichern