Basisbegrippen

Fouten

Gemlead antwoordt met een HTTP-status en een JSON-fout waarvan type en code nooit veranderen, zodat je code erop kan reageren.

Het foutobject

Elke fout heeft dezelfde vorm. message is voor mensen en kan veranderen, type en code zijn voor je code. Elke response, fout of niet, heeft ook de header Request-Id.

Attributen

typestring
De categorie van de fout, één per HTTP-status.
codestring
Wat er precies misging. Zie de codes hieronder.
messagestring
Een zin die de fout uitlegt.
paramstring of null
De parameter die de fout veroorzaakt, als die er is.
request_idstring
De ID van het request, gelijk aan de header Request-Id. Stuur hem mee als je ons om hulp vraagt.
doc_urlstring
Deze pagina, bij de uitleg van de code.

Response400

{
  "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	Type	Betekenis
400	`invalid_request_error`	Het request heeft een ontbrekende, onbekende of ongeldige parameter. Een methode die het pad niet accepteert, krijgt ook dit type, met een 405.
401	`authentication_error`	Geen sleutel, een verkeerde sleutel of een ingetrokken sleutel.
403	`permission_error`	De sleutel is geldig maar mag dit niet, zoals een `read`-sleutel die wil schrijven, of een account met het abonnement Free of Starter.
404	`not_found_error`	Dit object bestaat niet op het account van de sleutel, of de route bestaat niet.
409	`idempotency_error`	Een `Idempotency-Key` is hergebruikt voor een ander request, of het eerste request met die sleutel loopt nog.
429	`rate_limit_error`	Te veel requests. Wacht `Retry-After` seconden.
500	`api_error`	Er ging bij ons iets mis, of 501 voor een endpoint dat nog niet beschikbaar is. Probeer het later opnieuw met dezelfde `Idempotency-Key`.

Foutcodes

Code	Status	Betekenis
`api_key_missing`	401	Het request heeft geen header `Authorization` of `X-Api-Key`.
`api_key_invalid`	401	Er komt geen sleutel overeen. Controleer of je hem helemaal hebt gekopieerd, inclusief `gl_live_`.
`api_key_revoked`	401	De sleutel is in de app ingetrokken. Maak een nieuwe aan.
`token_expired`	401	Een OAuth-toegangstoken van een AI-assistent is verlopen. De assistent vernieuwt het zelf.
`insufficient_scope`	403	De sleutel heeft de scope `read` en het request wijzigt gegevens. Gebruik een sleutel met `write`.
`plan_required`	403	De eigenaar van het account heeft het abonnement Free of Starter. De API werkt met Business en Enterprise, proefperiode inbegrepen, en dezelfde sleutel werkt weer zodra het account een van beide heeft.
`forbidden`	403	De gebruiker van de sleutel mag dit niet op dit X-account, zoals een teamlid dat het team wijzigt zonder admin te zijn, of dat een persona deelt.
`parameter_missing`	400	Er ontbreekt een verplichte parameter. `param` geeft aan welke.
`parameter_invalid`	400	Een parameter heeft een waarde die de API niet accepteert, zoals een score boven 100 of een datum die niet in ISO 8601 staat. `param` geeft aan welke.
`parameter_unknown`	400	De query of de body bevat een parameter die dit endpoint niet accepteert. `param` geeft aan welke.
`body_invalid`	400	De body is geen geldige JSON, of geen JSON-object.
`cursor_invalid`	400	De `cursor` komt niet van de API, of is gemaakt voor andere filters.
`idempotency_key_invalid`	400	De `Idempotency-Key` is langer dan 255 tekens.
`method_not_allowed`	405	Dit pad accepteert deze methode niet. De header `Allow` noemt de methodes die het wel accepteert.
`url_invalid`	400	Een webhook-URL is geen HTTPS, bevat inloggegevens, resolvet niet of wijst naar een privéadres.
`webhook_endpoint_limit_reached`	400	Het account heeft al 10 webhook-endpoints. Verwijder er eerst een.
`resource_already_exists`	400	Het bestaat al, zoals een bron die de persona al heeft met deze methode, of een zoekopdracht die er al in staat.
`limit_reached`	400	Een limiet is bereikt, zoals 100 persona's op een account, 500 zoekopdrachten op een persona of 50 kolommen op het bord.
`seed_source_refused`	400	Een startbron van een nieuwe persona wordt geweigerd, zoals een investeerder, een accelerator of een media-account. Die leveren geen kopers op.
`x_profile_not_found`	400	X heeft geen leesbaar profiel onder deze gebruikersnaam.
`lead_without_x_id`	400	De lead heeft nog geen X-account-ID, dus je kunt hem nog niet volgen.
`lead_not_convertible`	400	De lead hoort bij geen enkele persona, dus hij kan geen bron worden.
`campaign_archived`	400	De campagne is gearchiveerd. Dupliceer hem om hem opnieuw te laten draaien.
`campaign_not_started`	400	De campagne is een concept, dus er valt niets te pauzeren.
`campaign_flow_empty`	400	De flow van de campagne heeft nog geen stap. Voeg er een toe voordat je hem start.
`column_protected`	400	Deze kolom hoort bij het bord, zoals Inbox of een personakolom, en kan niet worden verwijderd.
`shared_account_has_campaigns`	400	Een X-account dat je uit een gedeelde persona haalt, heeft er nog campagnes op lopen. Verwijder die en probeer het opnieuw.
`owner_cannot_leave`	400	De eigenaar van een X-account kan het team niet verlaten. Verwijder in plaats daarvan de leden.
`translation_off`	400	De vertaling van het gesprek staat uit. Zet hem aan, of vertaal de berichten één voor één.
`recipient_not_messageable`	400	X heeft de DM geweigerd. De lead heeft zijn DM's dichtgezet of het account geblokkeerd.
`media_kind_unsupported`	400	Dit gesprek accepteert dit soort bestand niet. Een spraakbericht kan alleen in een X Chat-gesprek.
`x_session_expired`	409	De sessie van het X-account is verlopen. Koppel het opnieuw in de app en probeer het dan nog eens.
`assistant_busy`	409	Julien AI is nog bezig met een bericht in deze chat, of met 3 berichten van dit X-account. Wacht op dat antwoord en stuur je bericht daarna opnieuw.
`conversation_unavailable`	409	Het gesprek heeft nog geen X-gebruiker om naar te schrijven.
`resource_missing`	404	Geen object met deze ID op het account van de sleutel. Een ID van een ander account geeft hetzelfde antwoord.
`route_not_found`	404	Geen endpoint op dit pad.
`idempotency_key_reused`	409	Deze `Idempotency-Key` is de afgelopen 24 uur gebruikt voor een andere methode, een ander pad of een andere body.
`idempotency_key_in_use`	409	Het eerste request met deze `Idempotency-Key` loopt nog. Probeer het over een seconde opnieuw.
`rate_limit_exceeded`	429	Meer dan 120 requests in een minuut met deze sleutel. Wacht `Retry-After` seconden.
`export_rate_limit_exceeded`	429	Meer dan 10 exports in een uur op dit account.
`dm_paused`	429	X beperkt de DM's van het account tijdelijk. `Retry-After` geeft aan wanneer ze weer kunnen.
`dm_rate_limited`	429	Meer dan 10 DM's in een minuut vanaf dit account.
`dm_daily_limit`	429	Vandaag, in UTC, al 300 DM's vanaf dit account, of het eigen dagquotum dat X voor dit account hanteert.
`assistant_rate_limited`	429	Meer dan 6 berichten aan Julien AI in een minuut vanaf dit X-account, of 150 in een uur voor de eigenaar, de chat in de app meegerekend.
`assistant_daily_limit`	429	Vandaag, in UTC, al 100 berichten aan Julien AI vanaf dit X-account.
`passcode_rate_limited`	429	Meer dan 5 pogingen met de X Chat-code in een uur op dit account. X telt elke poging.
`internal_error`	500	Een onverwachte fout bij ons. Met de `request_id` vinden we hem terug.
`request_timeout`	500	Het request duurde te lang. Probeer het opnieuw, met dezelfde `Idempotency-Key` als het gegevens wijzigt.
`not_implemented`	501	Dit endpoint is nog niet beschikbaar.
`upstream_unavailable`	502	X of een dienst van Gemlead reageerde niet. Er is niets veranderd, probeer het over een minuut opnieuw.

Fouten afhandelen

400, 401, 403 en 404 slagen nooit zolang je niets verandert. Pas het request aan voordat je het opnieuw verstuurt.
409 met idempotency_key_in_use slaagt een seconde later wel. Probeer het opnieuw met dezelfde Idempotency-Key.
429 slaagt wel na Retry-After seconden. Zie Rate limits.
500 kun je na een korte pauze opnieuw proberen. Stuur dezelfde Idempotency-Key mee bij requests die gegevens wijzigen, zodat niets twee keer gebeurt.
Log de request_id van elke fout. Daarmee vinden we het request binnen enkele seconden terug.