Grundlagen

Fehler

Gemlead antwortet mit einem HTTP-Status und einem JSON-Fehler, dessen type und code sich nie ändern, damit dein Code darauf verzweigen kann.

Das Fehlerobjekt

Jeder Fehler hat dieselbe Form. message ist für Menschen und kann sich ändern, type und code sind für deinen Code. Jede Antwort, ob Fehler oder nicht, enthält außerdem ihren Header Request-Id.

Attribute

typestring
Die Fehlerfamilie, eine pro HTTP-Status.
codestring
Was genau schiefgelaufen ist. Siehe die Codes unten.
messagestring
Ein Satz, der den Fehler erklärt.
paramstring oder null
Der fehlerhafte Parameter, falls es einen gibt.
request_idstring
Die ID der Anfrage, identisch mit ihrem Header Request-Id. Schicke sie uns, wenn du Hilfe brauchst.
doc_urlstring
Diese Seite, beim Eintrag des Codes.

Antwort400

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "score_min must be an integer from 0 to 100.",
    "param": "score_min",
    "request_id": "req_7Hq2LmX9pT4vK1sN",
    "doc_url": "https://gemlead.ai/docs/errors#parameter_invalid"
  }
}

HTTP-Statuscodes

Status	Typ	Bedeutung
400	`invalid_request_error`	In der Anfrage fehlt ein Parameter, oder einer ist unbekannt oder ungültig. Eine Methode, die der Pfad nicht unterstützt, ergibt ebenfalls diesen Typ, mit dem Status 405.
401	`authentication_error`	Kein Schlüssel, ein falscher oder ein widerrufener Schlüssel.
403	`permission_error`	Der Schlüssel ist gültig, darf das aber nicht, etwa ein `read`-Schlüssel, der schreibt, oder ein Konto im Free- oder Starter-Tarif.
404	`not_found_error`	Dieses Objekt gibt es im Konto des Schlüssels nicht, oder diese Route existiert nicht.
409	`idempotency_error`	Ein `Idempotency-Key` wurde für eine andere Anfrage wiederverwendet, oder seine erste Anfrage läuft noch.
429	`rate_limit_error`	Zu viele Anfragen. Warte die Sekunden aus `Retry-After` ab.
500	`api_error`	Bei uns ist etwas schiefgelaufen, oder 501 für einen Endpoint, den es noch nicht gibt. Versuche es später mit demselben `Idempotency-Key` noch einmal.

Fehlercodes

Code	Status	Bedeutung
`api_key_missing`	401	Die Anfrage hat keinen `Authorization`- oder `X-Api-Key`-Header.
`api_key_invalid`	401	Kein Schlüssel passt. Prüfe, ob du ihn vollständig kopiert hast, `gl_live_` eingeschlossen.
`api_key_revoked`	401	Der Schlüssel wurde in der App widerrufen. Erstelle einen neuen.
`token_expired`	401	Ein OAuth-Access-Token eines KI-Assistenten ist abgelaufen. Der Assistent erneuert es selbst.
`insufficient_scope`	403	Der Schlüssel hat den Scope `read`, die Anfrage ändert aber Daten. Nimm einen Schlüssel mit `write`.
`plan_required`	403	Der Inhaber des Kontos ist im Free- oder Starter-Tarif. Die API ist in Business und Enterprise enthalten, auch in der Testphase, und derselbe Schlüssel funktioniert wieder, sobald das Konto einen davon nutzt.
`forbidden`	403	Der Nutzer des Schlüssels darf das in diesem X-Konto nicht, etwa ein Mitglied, das das Team ändert, ohne Admin zu sein, oder eine Persona teilt.
`parameter_missing`	400	Ein Pflichtparameter fehlt. `param` nennt ihn.
`parameter_invalid`	400	Ein Parameter hat einen Wert, den die API nicht akzeptiert, etwa einen Score über 100 oder ein Datum, das nicht ISO 8601 entspricht. `param` nennt ihn.
`parameter_unknown`	400	Query oder Body enthalten einen Parameter, den dieser Endpoint nicht akzeptiert. `param` nennt ihn.
`body_invalid`	400	Der Body ist kein gültiges JSON oder kein JSON-Objekt.
`cursor_invalid`	400	Der `cursor` stammt nicht von der API oder wurde für andere Filter erstellt.
`idempotency_key_invalid`	400	Der `Idempotency-Key` ist länger als 255 Zeichen.
`method_not_allowed`	405	Dieser Pfad unterstützt diese Methode nicht. Der Header `Allow` listet die unterstützten auf.
`url_invalid`	400	Eine Webhook-URL ist kein HTTPS, enthält Zugangsdaten, lässt sich nicht auflösen oder zeigt auf eine private Adresse.
`webhook_endpoint_limit_reached`	400	Das Konto hat schon 10 Webhook-Endpoints. Lösche zuerst einen.
`resource_already_exists`	400	Das existiert bereits, etwa eine Quelle, die die Persona mit dieser Methode schon hat, oder eine ihrer Keyword-Suchen.
`limit_reached`	400	Ein Limit ist erreicht, etwa 100 Personas pro Konto, 500 Keyword-Suchen pro Persona oder 50 Spalten im Board.
`seed_source_refused`	400	Eine Startquelle für eine neue Persona wird abgelehnt, etwa ein Investor, ein Accelerator oder ein Medienkonto. Solche Konten bringen keine Käufer.
`x_profile_not_found`	400	X hat unter diesem Nutzernamen kein lesbares Profil.
`lead_without_x_id`	400	Der Lead hat noch keine X-Konto-ID, daher kann man ihm nicht folgen.
`lead_not_convertible`	400	Der Lead gehört zu keiner Persona und kann daher keine Quelle werden.
`campaign_archived`	400	Die Kampagne ist archiviert. Dupliziere sie, um sie erneut laufen zu lassen.
`campaign_not_started`	400	Die Kampagne ist ein Entwurf, es gibt also nichts zu pausieren.
`campaign_flow_empty`	400	Der Ablauf der Kampagne hat noch keinen Schritt. Füge einen hinzu, bevor du sie startest.
`column_protected`	400	Diese Spalte gehört zum Board, etwa Posteingang oder eine Persona-Spalte, und lässt sich nicht löschen.
`shared_account_has_campaigns`	400	Ein X-Konto, das du aus einer geteilten Persona nimmst, hat dort noch Kampagnen. Lösche sie und versuche es dann noch einmal.
`owner_cannot_leave`	400	Der Inhaber eines X-Kontos kann sein Team nicht verlassen. Entferne stattdessen die Mitglieder.
`translation_off`	400	Die Übersetzung der Unterhaltung ist aus. Schalte sie ein oder übersetze jeweils eine Nachricht.
`recipient_not_messageable`	400	X hat die DM abgelehnt. Der Lead hat seine DMs geschlossen oder das Konto blockiert.
`media_kind_unsupported`	400	Diese Unterhaltung unterstützt diese Art von Datei nicht. Eine Sprachnachricht braucht eine Unterhaltung in X Chat.
`x_session_expired`	409	Die Sitzung des X-Kontos ist abgelaufen. Verbinde es in der App neu und versuche es dann noch einmal.
`assistant_busy`	409	Julien AI beantwortet noch eine Nachricht dieses Chats oder 3 Nachrichten dieses X-Kontos. Warte die Antwort ab und sende dann erneut.
`conversation_unavailable`	409	Die Unterhaltung hat noch keinen X-Nutzer, an den geschrieben werden kann.
`resource_missing`	404	Kein Objekt mit dieser ID im Konto des Schlüssels. Eine ID eines anderen Kontos ergibt dieselbe Antwort.
`route_not_found`	404	Unter diesem Pfad gibt es keinen Endpoint.
`idempotency_key_reused`	409	Dieser `Idempotency-Key` wurde in den letzten 24 Stunden für eine andere Methode, einen anderen Pfad oder einen anderen Body verwendet.
`idempotency_key_in_use`	409	Die erste Anfrage mit diesem `Idempotency-Key` läuft noch. Versuche es in einer Sekunde erneut.
`rate_limit_exceeded`	429	Mehr als 120 Anfragen pro Minute mit diesem Schlüssel. Warte die Sekunden aus `Retry-After` ab.
`export_rate_limit_exceeded`	429	Mehr als 10 Exporte pro Stunde in diesem Konto.
`dm_paused`	429	X drosselt die DMs des Kontos gerade. `Retry-After` gibt an, wann es weitergeht.
`dm_rate_limited`	429	Mehr als 10 DMs pro Minute von diesem Konto.
`dm_daily_limit`	429	Dieses Konto hat an diesem UTC-Tag schon 300 DMs gesendet oder das Tageskontingent erreicht, das X selbst dafür setzt.
`assistant_rate_limited`	429	Mehr als 6 Nachrichten pro Minute an Julien AI von diesem X-Konto, oder 150 pro Stunde für seinen Inhaber, den Chat in der App eingerechnet.
`assistant_daily_limit`	429	Dieses X-Konto hat an diesem UTC-Tag schon 100 Nachrichten an Julien AI gesendet.
`passcode_rate_limited`	429	Mehr als 5 Versuche mit dem X Chat-Code pro Stunde in diesem Konto. X zählt jeden Versuch.
`internal_error`	500	Ein unerwarteter Fehler bei uns. Mit der `request_id` finden wir ihn.
`request_timeout`	500	Die Anfrage hat zu lange gedauert. Sende sie erneut, mit demselben `Idempotency-Key`, wenn sie Daten ändert.
`not_implemented`	501	Dieser Endpoint ist noch nicht verfügbar.
`upstream_unavailable`	502	X oder ein Gemlead-Dienst hat nicht geantwortet. Nichts wurde geändert, versuche es in einer Minute erneut.

Fehler behandeln

Bei 400, 401, 403 und 404 hilft kein erneuter Versuch. Korrigiere die Anfrage, bevor du sie erneut sendest.
Bei 409 mit idempotency_key_in_use klappt es eine Sekunde später. Wiederhole die Anfrage mit demselben Idempotency-Key.
Bei 429 klappt es nach Retry-After Sekunden. Siehe Rate Limits.
500 kannst du nach einer kurzen Pause wiederholen. Sende bei Anfragen, die Daten ändern, denselben Idempotency-Key, damit nichts doppelt passiert.
Logge die request_id jedes Fehlers. Damit finden wir die Anfrage in Sekunden.