Referencia de errores

Todos los códigos de error que devuelve SociaHive, qué significan y cómo recuperarte.

Toda respuesta de SociaHive que no sea 2xx incluye una cadena code estable. Esa cadena es más fiable que el estado HTTP para la lógica de ramificación: los estados pueden cambiar entre códigos cercanos (por ejemplo, 422 frente a 400) a medida que hacemos la validación más estricta, pero el valor de code forma parte de la API pública.

Estructura

{
  "error": "Human-readable message",
  "code": "rate_limit",
  "details": { "...": "optional context, schema varies per code" }
}

En los SDK de Node y de Python, toda respuesta que no sea 2xx lanza un SociaHiveError cuyo campo .code coincide con la tabla de abajo.

Códigos

code	HTTP	Cuándo se produce	Qué hacer
`auth_error`	401	No se envió `X-API-Key` ni token bearer de OAuth, o tiene un formato incorrecto o no es válido; la clave se revocó; la clave no tiene el scope necesario para esta herramienta.	Confirma que la clave está definida, que tiene el scope correcto y que no se rotó. Los SDK lo exponen con `err.isAuthError`.
`not_found`	404	El recurso solicitado (flujo, publicación, cuenta) no existe O pertenece a otro usuario.	Revisa el ID. Ten en cuenta que también se devuelve 404 cuando el recurso existe pero tu clave no puede acceder a él (así no se filtra información sobre los datos de otros usuarios).
`invalid_input`	400	El cuerpo o la consulta de la solicitud no pasó el esquema de entrada: tipo incorrecto, falta un campo obligatorio, formato inválido.	El objeto `details` lista los campos que fallan. Corrige los datos y reintenta.
`validation_error`	422	La entrada se interpretó, pero una regla de negocio la rechazó (por ejemplo, programar una publicación en el pasado o aplicar una etiqueta con caracteres reservados).	Lee `details.reason` para saber qué regla se incumplió. No se puede reintentar sin cambiar la entrada.
`conflict`	409	Colisión con una restricción de unicidad: por ejemplo, ya existe una suscripción de webhook con el mismo `target_url`, o dos pasos de un flujo comparten un ID.	Actualiza el recurso existente o elige otro identificador.
`keyword_conflict`	409	Una palabra clave que intentas registrar en el disparador de un flujo ya la usa otro flujo activo de la misma cuenta.	Desactiva el otro flujo, elige otra palabra clave o limítala a una publicación concreta.
`state_error`	409	El recurso está en un estado que no admite esta operación. Caso habitual: editar pasos de un flujo `published`.	Para editar un flujo activo: `duplicate_flow` → edita la copia en borrador → `activate_flow`. El campo `details` del error suele incluir un campo `suggestion`.
`tier_error`	402	Tu plan no incluye esta función; por ejemplo, los pasos de división aleatoria en el plan Gratis o las herramientas de chat en vivo sin Pro o superior.	Actualiza tu plan o quita la función del flujo. `details.required_tier` indica el mínimo.
`limit_reached`	422	Un recurso contabilizado llegó al tope de su plan: suscripciones de webhook, cuentas conectadas, publicaciones programadas por mes, etc.	Elimina un recurso existente del mismo tipo o actualiza tu plan.
`automated_account_limit`	403	Activar la automatización (activar un flujo o activar Respuestas con IA o Comentarios con IA) en una cuenta conectada que aún no está automatizada superaría el límite de cuentas automatizadas de tu plan (Gratis 0, Creator 1, Studio 4, Pro 10, Agency 100). Las cuentas que ya ejecutan automatización no se ven afectadas.	Desactiva la automatización en otra cuenta (desactiva sus flujos y desactiva Respuestas con IA / Comentarios con IA) o actualiza tu plan.
`no_account_selected`	400	Una herramienta de flujos o de estadísticas necesita el contexto de una cuenta conectada concreta, pero el agente no lo proporcionó (solo ocurre por MCP).	El selector de cuenta del encabezado del chat debería completarlo solo; si no lo hace, pasa `account_id` de forma explícita.
`rate_limit`	429	Superaste la cuota por minuto o la diaria.	Respeta `Retry-After` (segundos). `details.window` de la respuesta indica qué grupo se superó (read / write / expensive / daily). Consulta Límites de frecuencia.
`upstream_error`	502 / 503	Una plataforma de la que dependemos (Instagram, Meta, OpenAI, etc.) devolvió un error o agotó el tiempo de espera.	Suele ser pasajero: reintenta con espera exponencial. El campo `details.upstream` indica la plataforma.
`unknown_error`	500	Algo que no anticipamos.	Reintenta una vez. Si persiste, reporta el problema con el valor de `details.request_id`.

Sobre especial: pending_confirmation

Las herramientas destructivas (delete_*, publish_post_now, disconnect_account) no devuelven un error en la primera llamada: devuelven un sobre de confirmación:

{
  "__mcp_envelope": "pending_confirmation",
  "confirmToken": "...",
  "summary": "Delete flow 'Welcome series' — 4 nodes, 1.2K executions",
  "affectedEntities": [{ "type": "flow", "id": "..." }]
}

Devuelve __confirmToken en la segunda llamada, dentro de los 5 minutos siguientes. Consulta la sección Flujo de confirmación de la guía de configuración del MCP.

Ayudas de los SDK

Indicadores prácticos en los SDK

Las clases de error de los SDK de Node y de Python exponen indicadores ya calculados para los códigos por los que más ramificarás:

err.isAuthError: verdadero para auth_error
err.isRateLimited: verdadero para rate_limit
err.isNotFound: verdadero para not_found
err.isStateError: verdadero para state_error y conflict

Úsalos en lugar de comparar cadenas con err.code siempre que puedas.

Qué NO aparece en esta lista

Los fallos que ocurren solo a nivel HTTP (por ejemplo, un 502 de Cloudflare antes de que la solicitud llegue a nosotros): no tienen code porque nunca llegaron a la aplicación.
Los errores del lado de la plataforma que mostramos sin transformar: consulta details.upstream en upstream_error.

Si te encuentras con un código que no está en esta tabla, escríbenos con el cuerpo de la respuesta: la tabla es la fuente de verdad, pero es posible que el producto ya devuelva un código nuevo que todavía no llegó a la documentación.