Conceptos básicos

Errores

Gemlead responde con un código de estado HTTP y un error en JSON cuyos type y code nunca cambian, para que tu código actúe en función de ellos.

El objeto error

Todos los errores tienen la misma forma. message está pensado para las personas y puede cambiar, type y code son para tu código. Cada respuesta, sea un error o no, lleva además su encabezado Request-Id.

Atributos

typestring
La familia del error, una por código de estado HTTP.
codestring
Qué falló exactamente. Consulta los códigos más abajo.
messagestring
Una frase que explica el error.
paramstring o null
El parámetro que falla, si lo hay.
request_idstring
El ID de la solicitud, el mismo que su encabezado Request-Id. Envíanoslo cuando necesites ayuda.
doc_urlstring
Esta página, en la entrada de ese código.

Respuesta400

{
  "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"
  }
}

Códigos de estado HTTP

Estado	Tipo	Significado
400	`invalid_request_error`	A la solicitud le falta un parámetro, o tiene uno desconocido o no válido. Un método que la ruta no acepta también recibe este tipo, con un 405.
401	`authentication_error`	Sin clave, con una clave incorrecta o con una clave revocada.
403	`permission_error`	La clave es válida pero no puede hacer esto, como una clave `read` que escribe o una cuenta en el plan Free o Starter.
404	`not_found_error`	Ese objeto no existe en la cuenta de la clave, o esa ruta no existe.
409	`idempotency_error`	Se reutilizó una `Idempotency-Key` para otra solicitud, o su primera solicitud sigue en curso.
429	`rate_limit_error`	Demasiadas solicitudes. Espera `Retry-After` segundos.
500	`api_error`	Algo falló por nuestra parte, o 501 para un endpoint que aún no está disponible. Reintenta más tarde con la misma `Idempotency-Key`.

Códigos de error

Código	Estado	Significado
`api_key_missing`	401	La solicitud no tiene encabezado `Authorization` ni `X-Api-Key`.
`api_key_invalid`	401	Ninguna clave coincide. Comprueba que la copiaste entera, `gl_live_` incluido.
`api_key_revoked`	401	La clave se revocó en la app. Crea una nueva.
`token_expired`	401	Caducó un token de acceso OAuth de un asistente de IA. El asistente lo renueva solo.
`insufficient_scope`	403	La clave tiene el scope `read` y la solicitud modifica datos. Usa una clave con `write`.
`plan_required`	403	El propietario de la cuenta tiene el plan Free o Starter. La API funciona en Business y Enterprise, prueba incluida, y la misma clave vuelve a funcionar en cuanto la cuenta pasa a uno de los dos.
`forbidden`	403	El usuario de la clave no puede hacer esto en la cuenta de X, como un miembro que modifica el equipo sin ser admin, o que comparte un buyer persona.
`parameter_missing`	400	Falta un parámetro obligatorio. `param` lo indica.
`parameter_invalid`	400	Un parámetro tiene un valor que la API no acepta, como una puntuación por encima de 100 o una fecha que no está en ISO 8601. `param` lo indica.
`parameter_unknown`	400	La consulta o el cuerpo tiene un parámetro que este endpoint no acepta. `param` lo indica.
`body_invalid`	400	El cuerpo no es un JSON válido, o no es un objeto JSON.
`cursor_invalid`	400	El `cursor` no es uno que haya dado la API, o se creó para otros filtros.
`idempotency_key_invalid`	400	La `Idempotency-Key` tiene más de 255 caracteres.
`method_not_allowed`	405	Esta ruta no acepta este método. El encabezado `Allow` lista los que acepta.
`url_invalid`	400	Una URL de webhook no es HTTPS, lleva credenciales, no se resuelve o apunta a una dirección privada.
`webhook_endpoint_limit_reached`	400	La cuenta ya tiene 10 endpoints de webhook. Elimina uno primero.
`resource_already_exists`	400	Ya existe, como una fuente que el buyer persona ya tiene con este método o una búsqueda por palabras clave que ya tiene.
`limit_reached`	400	Se alcanzó un límite, como 100 buyer personas en una cuenta, 500 búsquedas por palabras clave en un buyer persona o 50 columnas en el tablero.
`seed_source_refused`	400	Se rechaza una fuente inicial de un buyer persona nuevo, como un inversor, una aceleradora o un medio. No traen compradores.
`x_profile_not_found`	400	X no tiene ningún perfil legible con este nombre de usuario.
`lead_without_x_id`	400	El lead aún no tiene ID de cuenta de X, así que no se puede seguir.
`lead_not_convertible`	400	El lead no pertenece a ningún buyer persona, así que no puede convertirse en fuente.
`campaign_archived`	400	La campaña está archivada. Duplícala para volver a lanzarla.
`campaign_not_started`	400	La campaña es un borrador, así que no hay nada que pausar.
`campaign_flow_empty`	400	El flujo de la campaña aún no tiene pasos. Añade uno antes de lanzarla.
`column_protected`	400	Esta columna es del propio tablero, como Bandeja de entrada o una columna de buyer persona, y no se puede eliminar.
`shared_account_has_campaigns`	400	La cuenta de X que quitas de un buyer persona compartido aún tiene campañas con él. Elimínalas y vuelve a intentarlo.
`owner_cannot_leave`	400	El propietario de una cuenta de X no puede salir de su equipo. En su lugar, quita a los miembros.
`translation_off`	400	La traducción de la conversación está desactivada. Actívala o traduce los mensajes de uno en uno.
`recipient_not_messageable`	400	X rechazó el DM. El lead cerró sus DM o bloqueó la cuenta.
`media_kind_unsupported`	400	La conversación no admite este tipo de archivo. Una nota de voz necesita una conversación de X Chat.
`x_session_expired`	409	La sesión de la cuenta de X caducó. Vuelve a conectarla en la app e inténtalo de nuevo.
`assistant_busy`	409	Julien AI sigue respondiendo a un mensaje de este chat, o a 3 mensajes de esta cuenta de X. Espera esa respuesta y vuelve a enviar.
`conversation_unavailable`	409	La conversación aún no tiene un usuario de X al que escribir.
`resource_missing`	404	No hay ningún objeto con este ID en la cuenta de la clave. Un ID de otra cuenta da la misma respuesta.
`route_not_found`	404	No hay ningún endpoint en esta ruta.
`idempotency_key_reused`	409	Esta `Idempotency-Key` se usó en las últimas 24 horas con otro método, ruta o cuerpo.
`idempotency_key_in_use`	409	La primera solicitud con esta `Idempotency-Key` sigue en curso. Reintenta en un segundo.
`rate_limit_exceeded`	429	Más de 120 solicitudes en un minuto con esta clave. Espera `Retry-After` segundos.
`export_rate_limit_exceeded`	429	Más de 10 exportaciones en una hora en esta cuenta.
`dm_paused`	429	X limita por ahora los DM de la cuenta. `Retry-After` indica cuándo se reanudan.
`dm_rate_limited`	429	Más de 10 DM en un minuto desde esta cuenta.
`dm_daily_limit`	429	300 DM hoy, en UTC, desde esta cuenta, o la cuota diaria que X le asigna.
`assistant_rate_limited`	429	Más de 6 mensajes a Julien AI en un minuto desde esta cuenta de X, o 150 en una hora para su propietario, chat de la app incluido.
`assistant_daily_limit`	429	100 mensajes a Julien AI hoy, en UTC, desde esta cuenta de X.
`passcode_rate_limited`	429	Más de 5 intentos de código de X Chat en una hora en esta cuenta. X cuenta cada intento.
`internal_error`	500	Un error inesperado por nuestra parte. El `request_id` nos ayuda a encontrarlo.
`request_timeout`	500	La solicitud tardó demasiado. Reinténtala, con la misma `Idempotency-Key` si modifica datos.
`not_implemented`	501	Este endpoint aún no está disponible.
`upstream_unavailable`	502	X o un servicio de Gemlead no respondió. No ha cambiado nada, vuelve a intentarlo en un minuto.

Gestiona los errores

400, 401, 403 y 404 vuelven a fallar si repites la solicitud tal cual. Corrígela antes de enviarla de nuevo.
409 con idempotency_key_in_use se resuelve un segundo después. Reintenta con la misma Idempotency-Key.
429 se resuelve al cabo de Retry-After segundos. Consulta Límites de uso.
500 se puede reintentar tras una breve espera. Envía la misma Idempotency-Key en las solicitudes que modifican datos, así nada ocurre dos veces.
Registra el request_id de cada error, con él encontramos la solicitud en segundos.