ArgorantDocs

Errores y límites

La forma única de los errores, todos los códigos de error, el id de solicitud, los límites de solicitudes por plan, los límites de búsquedas y recuentos, los límites diarios, las páginas y los reintentos seguros.

Una sola forma de error

Todas las respuestas de error tienen el mismo aspecto. Lee error.code para decidir qué hacer y muestra error.message a las personas. El mensaje es una frase sencilla.

JSON
{
  "error": {
    "code": "insufficient_credits",
    "message": "Revealing these people costs 1 credit each and the account has none left. Pick a plan at https://argorant.com/pricing.",
    "details": { "needed": 25, "balance": 0 }
  },
  "request_id": "req_8f2c1d9e0b7a4c3e9f1a2b3c4d5e6f70",
  "detail": "..."
}

detail contiene la forma antigua del error para los clientes escritos antes de esta forma. El código nuevo debería leer error.

Códigos de error

CódigoEstadoQué significa y qué hacer
invalid_request400A la solicitud le falta algo o un valor es incorrecto. El mensaje dice qué corregir.
launch_blocked400La campaña todavía no se puede lanzar. details.blockers indica lo que falta.
unauthorized401No hay clave de API, o la clave es incorrecta o está revocada.
api_key_required401Esta ruta necesita una clave de API o un inicio de sesión del conector, no una sesión del navegador.
plan_required402El plan de la cuenta no incluye esto. El mensaje nombra el plan que sí lo incluye. Una clave de una cuenta sin plan y sin créditos lo recibe en cada llamada.
insufficient_credits402No hay créditos suficientes para esta llamada. details indica cuántos hacen falta. No se ha cobrado nada.
scope_missing403A la clave le falta un scope que necesita esta llamada. Crea una clave con ese scope.
permission_missing403Tu rol en el espacio de trabajo no permite esta acción.
forbidden403Esta acción no está permitida para esta cuenta.
not_found404No existe ese elemento en tu espacio de trabajo. Los elementos de otros espacios de trabajo responden igual.
route_not_found404No existe ese endpoint. Comprueba la ruta en la referencia.
method_not_allowed405La ruta existe, pero no con este método HTTP. details.allowed indica los métodos.
conflict409El elemento está en un estado que no lo permite, por ejemplo al borrar una campaña en curso.
idempotency_conflict409Este Idempotency-Key ya se usó con otro cuerpo.
idempotency_in_progress409Una solicitud con este Idempotency-Key todavía se está ejecutando. Espera y vuelve a intentarlo.
gone410El elemento caducó, por ejemplo un archivo de exportación más antiguo que su tiempo de conservación.
quote_expired410El presupuesto es demasiado antiguo. Pide un presupuesto nuevo y vuelve a confirmar.
validation_error422Un campo tiene el tipo incorrecto o falta. details.fields indica cada problema.
access_key_activation_required428Esta clave de acceso por invitación todavía no está activa. Confirma primero el correo en details.claim_url.
rate_limited429Demasiadas solicitudes en este minuto o en 10 segundos, demasiadas búsquedas y recuentos en este minuto, o más de 200 personas desbloqueadas en un minuto. Espera los segundos de Retry-After.
daily_limit_reached429Se agotó un límite diario: el límite de la clave para este tipo de llamada, o los correos nuevos al día de una cuenta sin plan. details.action indica cuál. Se reinicia a medianoche UTC.
internal_error500Algo falló por nuestra parte. Vuelve a intentarlo; indica el id de solicitud si sigue fallando.
unavailable503Una parte del servicio está ocupada o en pausa. Vuelve a intentarlo en un minuto.
confirmation_required400Un pedido necesita confirmed=true, enviado solo después de que la persona que paga haya dicho que sí.
invalid_webhook_url400La dirección del webhook debe ser una dirección pública https://.
invalid_webhook_events400Un nombre de evento es desconocido o no se indicó ningún evento. details.invalid indica los nombres desconocidos.
webhook_limit_reached400Tienes 10 webhooks activados, o 50 en total contando los desactivados. Borra uno o desactiva uno primero. Cada miembro del equipo tiene los suyos.
event_not_subscribed400Una llamada de prueba nombró un evento que el webhook no recibe. details.events indica los que sí recibe.
company_credits_required402Un perfil completo de empresa cuesta créditos y la cuenta tiene muy pocos. details.teaser contiene la parte gratis; no se ha cobrado nada.
search_busy503La búsqueda está ocupada ahora mismo. Vuelve a intentarlo en unos segundos.
phones_not_in_plan402Los números de teléfono vienen con el plan Pro. No se ha cobrado nada.
card_not_charged402No se cobró la tarjeta guardada. No se compró nada; paga con un enlace de pago.
owner_only403Solo el propietario del espacio de trabajo puede hacer esto, por ejemplo pedir o cancelar buzones.
quote_not_found404El presupuesto no existe o pertenece a otra persona. Pide un presupuesto nuevo.
charge_in_progress409Este presupuesto se está cobrando ahora mismo. Revisa el pedido en un momento.
not_enough_names409No se encontraron suficientes nombres de dominio libres. Envía tú algunos dominios.
not_paid409El pedido todavía no está pagado, así que no hay nada que cancelar.
reason_required422Cancelar buzones necesita un motivo de las opciones de la lista.
not_connected409Esa herramienta todavía no está conectada. Conéctala primero en Configuración, Herramientas conectadas.
unsupported_tool409Esta herramienta conectada no puede recibir personas directamente. Envíale una exportación desde la página Exportaciones.
tool_key_rejected409La herramienta conectada no aceptó la clave guardada. Vuelve a conectarla en Configuración, Herramientas conectadas.
price_mismatch409El precio que mostraste a la persona no es el precio presupuestado. Muestra el precio presupuestado y vuelve a preguntar.
quote_other_session409El presupuesto se hizo con otra clave u otra conexión. Pide aquí un presupuesto nuevo y vuelve a confirmar.
export_failed409La exportación no terminó, así que no hay nada que enviar. Vuelve a ejecutar la exportación.
sign_in_failed422El servidor de correo no aceptó el inicio de sesión, así que el buzón no se conectó. details.test indica qué falló para el envío y para la lectura de respuestas.
campaign_not_started409La campaña es un borrador, así que no hay nada que pausar. Lánzala primero.
finder_rate_limit429Más de 30 búsquedas individuales en el buscador de correos en este minuto. Espera los segundos de Retry-After.
finder_daily_limit4292.000 búsquedas en el buscador de correos hoy. Se reinicia a medianoche UTC.
finder_miss_rate_throttle429La mayoría de las búsquedas recientes no encontraron nada, así que las búsquedas se reducen a 20 por hora durante un tiempo. Revisa los nombres y los dominios.

Algunas operaciones añaden un código propio, como confirmation_required o quote_not_found. Cada operación indica sus códigos en la referencia. Trata un código que no conoces según su estado HTTP.

El id de solicitud

Cada respuesta incluye un encabezado X-Request-Id, y cada error lo repite como request_id. Envía tu propio id en el encabezado X-Request-Id (de 8 a 64 letras, dígitos, puntos, guiones o guiones bajos) para encontrar una llamada en tus propios logs. Indica el id cuando pidas ayuda.

Solicitudes por minuto

Cada clave puede enviar este número de solicitudes por minuto, y hasta el segundo número en cualquier intervalo de 10 segundos.

PlanSolicitudes por minutoEn 10 segundos
Sin plan, clave de API o CLI3015
Sin plan, asistente de IA6020
Starter6015
Pro24060
Scale600150
Hyperscale1.200300

Sin plan cubre los primeros 7 días de una cuenta que todavía no ha elegido un plan y las cuentas que usan créditos comprados antes. Una prueba de un plan tiene los límites de ese plan. Una clave de una cuenta sin plan y sin créditos recibe 402 plan_required en cada llamada, incluida GET /api/v1/account.

Cada respuesta a una llamada con clave incluye X-RateLimit-Limit (solicitudes por minuto), X-RateLimit-Remaining (solicitudes que quedan en este minuto) y X-RateLimit-Reset (segundos hasta que empieza el siguiente minuto). Por encima de cualquiera de los dos límites recibes 429 rate_limited con un encabezado Retry-After. Espera esos segundos y vuelve a intentarlo.

Desbloquear personas tiene un límite más en todos los planes: una cuenta desbloquea hasta 200 personas por minuto. Por encima también recibes 429 rate_limited.

Búsquedas y recuentos

Las búsquedas, los recuentos y las vistas previas son gratis. Se limitan por cuenta, sumando todas sus claves y el conector, así que una segunda clave no da más.

PlanPor minutoRecuentos al díaFilas de vista previa al día
Sin plan, clave de API o CLI10500500
Sin plan, asistente de IA201.0001.000
Starter30sin límitesin límite
Pro60sin límitesin límite
Scale90sin límitesin límite
Hyperscale120sin límitesin límite

Sin plan, las búsquedas y los recuentos también incluyen X-RateLimit-Daily-Limit y X-RateLimit-Daily-Remaining. Una vista previa contiene hasta 10 personas por llamada.

Límites diarios por clave

Sin plan, cada clave también tiene límites diarios. Con un plan solo el buscador de correos tiene uno; los créditos limitan el resto. Los límites diarios se reinician a medianoche UTC. GET /api/v1/account muestra lo que queda hoy.

QuéPor díaPor llamada
Personas desbloqueadas, por filtros100 (sin límite con un plan)25
Filas de exportación50.000 (sin límite con un plan)50.000 por archivo, 500.000 por lote
Búsquedas en el buscador de correos2.00030 por minuto, listas de hasta 10.000 filas

Una cuenta sin plan también encuentra como máximo 10 correos nuevos al día en total: los desbloqueos, los resultados del buscador de correos y las filas de exportación cuentan juntos, y un correo que ya tenía no cuenta.

Por encima de un límite diario recibes 429 daily_limit_reached. Para más personas que el límite diario de desbloqueos, guarda una lista, expórtala o añádela a una campaña; esas vías están pensadas para miles de personas. El buscador de correos responde con sus propios códigos: finder_rate_limit (por minuto), finder_daily_limit (por día) y finder_miss_rate_throttle (la mayoría de las búsquedas no encontraron nada).

Páginas

Cada lista acepta limit y cursor. La respuesta mantiene su propia clave (por ejemplo campaigns o people) y añade total, limit, offset, next_cursor y has_more. Pasa next_cursor como cursor para obtener la página siguiente; es null en la última página. offset también funciona, si prefieres contar las filas tú mismo.

Algunas listas terminan antes o paginan a su manera. Las personas de una campaña se paginan con after puesto a next_after, en un orden fijo, y esas páginas no incluyen next_cursor. Las respuestas de una campaña se paginan igual, con after y next_after. La lista de campañas llega a las primeras 500 campañas; cursor pagina dentro de ellas. La bandeja de entrada, las respuestas de una campaña y las personas de una campaña también aceptan un filtro de fecha (updated_after y received_after, o created_after) en ISO 8601.

Shell
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"

Cuando total_is_estimate es true, total es el mínimo que hay, por ejemplo cuando una lista alcanzó su tamaño máximo.

Reintentos seguros

Envía un encabezado Idempotency-Key con cualquier escritura: crear, cambiar, borrar, responder, reenviar y todo lo que gaste créditos o dinero. Usa un valor aleatorio nuevo para cada acción nueva y el mismo valor cuando la reintentes.

  • La misma clave con el mismo cuerpo en 24 horas devuelve la primera respuesta, con el encabezado Idempotent-Replayed: true. Nada se hace dos veces.
  • La misma clave con otro cuerpo responde 409 idempotency_conflict.
  • Mientras la primera solicitud siga en curso, un reintento responde 409 idempotency_in_progress. Espera un momento y vuelve a intentarlo.
  • Los errores no se guardan, así que puedes corregir el problema y reintentar con la misma clave.
Shell
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}'

Campañas que no se pueden lanzar

POST /api/v1/campaigns/{id}/launch responde launch_blocked mientras falte algo, por ejemplo un correo, un buzón con capacidad disponible hoy o personas. details.blockers indica cada cosa en palabras sencillas. GET /api/v1/campaigns/{id} muestra la misma lista como launch_blockers, para que puedas resolverlo antes de intentarlo.

En esta página