Fehler und Limits

Eine Fehlerform

Jede Fehlerantwort sieht gleich aus. Lies error.code, um zu entscheiden, was zu tun ist, und zeig Menschen error.message. Die Meldung ist ein einfacher Satz (auf Englisch).

{
  "error": {
    "code": "insufficient_credits",
    "message": "Revealing these people costs 1 credit each and the account has none left. Buy credits or upgrade.",
    "details": { "needed": 25, "balance": 0 }
  },
  "request_id": "req_8f2c1d9e0b7a4c3e9f1a2b3c4d5e6f70",
  "detail": "..."
}

detail enthält die ältere Form des Fehlers für Clients, die vor dieser Form geschrieben wurden. Neuer Code sollte error lesen.

Fehlercodes

Manche Operationen haben einen eigenen Code, etwa confirmation_required oder quote_not_found. Jede Operation listet ihre Codes in der Referenz. Behandle einen Code, den du nicht kennst, nach seinem HTTP-Status.

Die Request-ID

Jede Antwort enthält einen Header X-Request-Id, und jeder Fehler wiederholt ihn als request_id. Schick deine eigene ID im Header X-Request-Id mit (8 bis 64 Buchstaben, Ziffern, Punkte, Bindestriche oder Unterstriche), um einen Aufruf in deinen eigenen Logs zu finden. Gib die ID an, wenn du Hilfe brauchst.

Anfragen pro Minute

Jeder Schlüssel darf so viele Anfragen pro Minute senden, und bis zur zweiten Zahl in beliebigen 10 Sekunden.

Jede Antwort auf einen Aufruf mit Schlüssel enthält X-RateLimit-Limit (Anfragen pro Minute), X-RateLimit-Remaining (verbleibende Anfragen in dieser Minute) und X-RateLimit-Reset (Sekunden bis die Minute neu beginnt). Über einem der beiden Limits bekommst du 429 rate_limited mit einem Header Retry-After. Warte so viele Sekunden und versuch es dann erneut.

Suchen und Zählungen

Suchen, Zählungen und Vorschauen sind kostenlos. Sie sind pro Konto begrenzt, über alle Schlüssel und den Connector hinweg. Ein zweiter Schlüssel bringt also nicht mehr.

In der Testphase enthalten Suchen und Zählungen zusätzlich X-RateLimit-Daily-Limit und X-RateLimit-Daily-Remaining. Eine Vorschau enthält bis zu 10 Personen pro Aufruf.

Tageslimits pro Schlüssel

In der Testphase und ohne Abo hat jeder Schlüssel zusätzlich Tageslimits. In einem Plan hat nur der E-Mail-Finder eins, den Rest begrenzen die Credits. Tageslimits werden um Mitternacht UTC zurückgesetzt. GET /api/v1/account zeigt, was heute noch übrig ist.

Über einem Tageslimit bekommst du 429 daily_limit_reached. Für mehr Personen als das Tageslimit beim Freischalten speicherst du eine Liste, exportierst sie oder fügst sie einer Kampagne hinzu. Diese Wege sind für Tausende Personen gemacht.

Seiten

Jede Liste nimmt limit und cursor. Die Antwort behält ihren eigenen Schlüssel (zum Beispiel campaigns oder people) und ergänzt total, limit, offset, next_cursor und has_more. Gib next_cursor als cursor mit, um die nächste Seite zu bekommen. Auf der letzten Seite ist er null. offset geht auch, wenn du Zeilen lieber selbst zählst.

curl "https://app.argorant.com/api/v1/campaigns?limit=25" -H "Authorization: Bearer $ARGORANT_API_KEY"
curl "https://app.argorant.com/api/v1/campaigns?limit=25&cursor=bzoyNQ" -H "Authorization: Bearer $ARGORANT_API_KEY"

Wenn total_is_estimate den Wert true hat, ist total das Minimum, zum Beispiel wenn eine Liste ihre maximale Größe erreicht hat.

Sichere Wiederholungen

Schick bei jedem schreibenden Aufruf einen Header Idempotency-Key mit: Anlegen, Ändern, Löschen, Antworten, Weiterleiten und allem, was Credits oder Geld kostet. Nimm für jede neue Aktion einen neuen Zufallswert und denselben Wert, wenn du sie wiederholst.

• Derselbe Schlüssel mit demselben Body innerhalb von 24 Stunden gibt die erste Antwort zurück, mit dem Header Idempotent-Replayed: true. Nichts passiert doppelt.
• Derselbe Schlüssel mit einem anderen Body antwortet mit 409 idempotency_conflict.
• Solange die erste Anfrage noch läuft, antwortet eine Wiederholung mit 409 idempotency_in_progress. Warte kurz und versuch es erneut.
• Fehler werden nicht gespeichert. Du kannst also das Problem beheben und mit demselben Schlüssel erneut senden.

curl -X POST "https://app.argorant.com/api/v1/exports" \
  -H "Authorization: Bearer $ARGORANT_API_KEY" \
  -H "Idempotency-Key: export-cfo-germany-2026-10-07" \
  -H "Content-Type: application/json" \
  -d '{"filters":{"title":"CFO","country":"Germany"},"limit":500}'

Kampagnen, die nicht starten können

POST /api/v1/campaigns/{id}/launch antwortet mit launch_blocked, solange etwas fehlt, zum Beispiel eine E-Mail, ein Postfach mit freier Kapazität für heute oder Personen. details.blockers listet jeden Punkt in einfachen Worten (auf Englisch). GET /api/v1/campaigns/{id} zeigt dieselbe Liste als launch_blockers, damit du alles vorher beheben kannst.