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.
{
"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ódigo | Estado | Qué significa y qué hacer |
|---|---|---|
invalid_request | 400 | A la solicitud le falta algo o un valor es incorrecto. El mensaje dice qué corregir. |
launch_blocked | 400 | La campaña todavía no se puede lanzar. details.blockers indica lo que falta. |
unauthorized | 401 | No hay clave de API, o la clave es incorrecta o está revocada. |
api_key_required | 401 | Esta ruta necesita una clave de API o un inicio de sesión del conector, no una sesión del navegador. |
plan_required | 402 | El 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_credits | 402 | No hay créditos suficientes para esta llamada. details indica cuántos hacen falta. No se ha cobrado nada. |
scope_missing | 403 | A la clave le falta un scope que necesita esta llamada. Crea una clave con ese scope. |
permission_missing | 403 | Tu rol en el espacio de trabajo no permite esta acción. |
forbidden | 403 | Esta acción no está permitida para esta cuenta. |
not_found | 404 | No existe ese elemento en tu espacio de trabajo. Los elementos de otros espacios de trabajo responden igual. |
route_not_found | 404 | No existe ese endpoint. Comprueba la ruta en la referencia. |
method_not_allowed | 405 | La ruta existe, pero no con este método HTTP. details.allowed indica los métodos. |
conflict | 409 | El elemento está en un estado que no lo permite, por ejemplo al borrar una campaña en curso. |
idempotency_conflict | 409 | Este Idempotency-Key ya se usó con otro cuerpo. |
idempotency_in_progress | 409 | Una solicitud con este Idempotency-Key todavía se está ejecutando. Espera y vuelve a intentarlo. |
gone | 410 | El elemento caducó, por ejemplo un archivo de exportación más antiguo que su tiempo de conservación. |
quote_expired | 410 | El presupuesto es demasiado antiguo. Pide un presupuesto nuevo y vuelve a confirmar. |
validation_error | 422 | Un campo tiene el tipo incorrecto o falta. details.fields indica cada problema. |
access_key_activation_required | 428 | Esta clave de acceso por invitación todavía no está activa. Confirma primero el correo en details.claim_url. |
rate_limited | 429 | Demasiadas 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_reached | 429 | Se 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_error | 500 | Algo falló por nuestra parte. Vuelve a intentarlo; indica el id de solicitud si sigue fallando. |
unavailable | 503 | Una parte del servicio está ocupada o en pausa. Vuelve a intentarlo en un minuto. |
confirmation_required | 400 | Un pedido necesita confirmed=true, enviado solo después de que la persona que paga haya dicho que sí. |
invalid_webhook_url | 400 | La dirección del webhook debe ser una dirección pública https://. |
invalid_webhook_events | 400 | Un nombre de evento es desconocido o no se indicó ningún evento. details.invalid indica los nombres desconocidos. |
webhook_limit_reached | 400 | Tienes 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_subscribed | 400 | Una llamada de prueba nombró un evento que el webhook no recibe. details.events indica los que sí recibe. |
company_credits_required | 402 | Un 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_busy | 503 | La búsqueda está ocupada ahora mismo. Vuelve a intentarlo en unos segundos. |
phones_not_in_plan | 402 | Los números de teléfono vienen con el plan Pro. No se ha cobrado nada. |
card_not_charged | 402 | No se cobró la tarjeta guardada. No se compró nada; paga con un enlace de pago. |
owner_only | 403 | Solo el propietario del espacio de trabajo puede hacer esto, por ejemplo pedir o cancelar buzones. |
quote_not_found | 404 | El presupuesto no existe o pertenece a otra persona. Pide un presupuesto nuevo. |
charge_in_progress | 409 | Este presupuesto se está cobrando ahora mismo. Revisa el pedido en un momento. |
not_enough_names | 409 | No se encontraron suficientes nombres de dominio libres. Envía tú algunos dominios. |
not_paid | 409 | El pedido todavía no está pagado, así que no hay nada que cancelar. |
reason_required | 422 | Cancelar buzones necesita un motivo de las opciones de la lista. |
not_connected | 409 | Esa herramienta todavía no está conectada. Conéctala primero en Configuración, Herramientas conectadas. |
unsupported_tool | 409 | Esta herramienta conectada no puede recibir personas directamente. Envíale una exportación desde la página Exportaciones. |
tool_key_rejected | 409 | La herramienta conectada no aceptó la clave guardada. Vuelve a conectarla en Configuración, Herramientas conectadas. |
price_mismatch | 409 | El precio que mostraste a la persona no es el precio presupuestado. Muestra el precio presupuestado y vuelve a preguntar. |
quote_other_session | 409 | El presupuesto se hizo con otra clave u otra conexión. Pide aquí un presupuesto nuevo y vuelve a confirmar. |
export_failed | 409 | La exportación no terminó, así que no hay nada que enviar. Vuelve a ejecutar la exportación. |
sign_in_failed | 422 | El 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_started | 409 | La campaña es un borrador, así que no hay nada que pausar. Lánzala primero. |
finder_rate_limit | 429 | Más de 30 búsquedas individuales en el buscador de correos en este minuto. Espera los segundos de Retry-After. |
finder_daily_limit | 429 | 2.000 búsquedas en el buscador de correos hoy. Se reinicia a medianoche UTC. |
finder_miss_rate_throttle | 429 | La 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.
| Plan | Solicitudes por minuto | En 10 segundos |
|---|---|---|
| Sin plan, clave de API o CLI | 30 | 15 |
| Sin plan, asistente de IA | 60 | 20 |
| Starter | 60 | 15 |
| Pro | 240 | 60 |
| Scale | 600 | 150 |
| Hyperscale | 1.200 | 300 |
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.
| Plan | Por minuto | Recuentos al día | Filas de vista previa al día |
|---|---|---|---|
| Sin plan, clave de API o CLI | 10 | 500 | 500 |
| Sin plan, asistente de IA | 20 | 1.000 | 1.000 |
| Starter | 30 | sin límite | sin límite |
| Pro | 60 | sin límite | sin límite |
| Scale | 90 | sin límite | sin límite |
| Hyperscale | 120 | sin límite | sin 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ía | Por llamada |
|---|---|---|
| Personas desbloqueadas, por filtros | 100 (sin límite con un plan) | 25 |
| Filas de exportación | 50.000 (sin límite con un plan) | 50.000 por archivo, 500.000 por lote |
| Búsquedas en el buscador de correos | 2.000 | 30 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.
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.
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.