Referência de erros

Todos os códigos de erro que o SociaHive devolve, o que significam e como se recuperar.

Toda resposta do SociaHive que não seja 2xx traz um code estável em texto. O texto é mais confiável do que o status HTTP para decidir o que fazer no seu código: os status podem mudar entre códigos vizinhos (por exemplo 422 e 400) à medida que deixamos a validação mais rigorosa, mas o valor de code faz parte da API pública.

Formato

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

Nos SDKs de Node e Python, toda resposta que não seja 2xx lança um SociaHiveError cujo campo .code corresponde à tabela abaixo.

Códigos

code	HTTP	Quando acontece	O que fazer
`auth_error`	401	`X-API-Key` / bearer OAuth ausente, malformado ou inválido; chave revogada; a chave não tem o escopo exigido por esta ferramenta.	Confirme se a chave está definida, tem o escopo certo e não foi trocada. Os SDKs expõem isso por `err.isAuthError`.
`not_found`	404	O recurso pedido (fluxo, post, conta) não existe OU pertence a outro usuário.	Confira o ID. Observação: o 404 também é devolvido quando o recurso existe, mas a sua chave não tem acesso a ele (sem vazar informação sobre os dados de outros usuários).
`invalid_input`	400	O corpo ou a consulta da requisição falhou no esquema de entrada: tipo errado, campo obrigatório ausente, formato inválido.	O objeto `details` lista os campos com problema. Corrija o conteúdo e tente de novo.
`validation_error`	422	A entrada foi interpretada, mas uma regra de negócio a rejeitou (por exemplo, agendar um post no passado ou aplicar uma tag com caracteres reservados).	Leia `details.reason` para saber qual regra foi violada. Não adianta repetir sem mudar a entrada.
`conflict`	409	Colisão de restrição de unicidade: por exemplo, já existe uma assinatura de webhook com o mesmo `target_url`, ou duas etapas do fluxo têm o mesmo ID.	Atualize o recurso existente ou escolha outro identificador.
`keyword_conflict`	409	Uma palavra-chave que você tenta registrar no gatilho de um fluxo já está em uso por outro fluxo ativo da mesma conta.	Desative o outro fluxo, escolha outra palavra-chave ou limite a um post específico.
`state_error`	409	O recurso está em um estado que não aceita esta operação. Caso comum: editar etapas de um fluxo `published`.	Para editar um fluxo publicado: `duplicate_flow` → edite a cópia em rascunho → `activate_flow`. O `details` do erro costuma trazer um campo `suggestion`.
`tier_error`	402	O seu plano não inclui este recurso: por exemplo, etapas randomizer no plano Free ou ferramentas de chat ao vivo sem Pro ou superior.	Faça upgrade do plano ou tire o recurso do fluxo. `details.required_tier` informa o mínimo.
`limit_reached`	422	Um recurso contado atingiu o limite do plano: assinaturas de webhook, contas conectadas, posts agendados por mês etc.	Exclua um recurso do mesmo tipo ou faça upgrade do plano.
`automated_account_limit`	403	Ativar a automação (publicar um fluxo ou ligar as Respostas com IA ou os Comentários com IA) em uma conta conectada que ainda não é automatizada passaria do limite de contas automatizadas do seu plano (Free 0, Creator 1, Studio 4, Pro 10, Agency 100). As contas que já rodam automação não são afetadas.	Desligue a automação de outra conta (despublique os fluxos dela e desligue as Respostas com IA e os Comentários com IA) ou faça upgrade do plano.
`no_account_selected`	400	Uma ferramenta de fluxo ou de métricas precisa do contexto de uma conta conectada específica, mas o agente não informou nenhuma (só acontece via MCP).	O seletor de conta no cabeçalho do chat deveria preencher isso automaticamente; se não preencher, envie `account_id` explicitamente.
`rate_limit`	429	Você passou da cota por minuto ou diária.	Respeite o `Retry-After` (em segundos). O `details.window` da resposta indica qual faixa estourou (read / write / expensive / daily). Veja Limites de requisições.
`upstream_error`	502 / 503	Uma plataforma da qual dependemos (Instagram, Meta, OpenAI etc.) devolveu um erro ou não respondeu a tempo.	Costuma ser passageiro: tente de novo com espera exponencial. O campo `details.upstream` informa a plataforma.
`unknown_error`	500	Algo que não previmos.	Tente mais uma vez. Se persistir, abra uma issue com o valor de `details.request_id`.

Envelope especial: pending_confirmation

As ferramentas destrutivas (delete_*, publish_post_now, disconnect_account) não dão erro na primeira chamada: elas devolvem um envelope de confirmação:

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

Envie o __confirmToken de volta na segunda chamada, em até 5 minutos. Veja a seção Fluxo de confirmação no guia de configuração do MCP.

Atalhos dos SDKs

Atalhos práticos nos SDKs

As classes de erro dos SDKs de Node e Python trazem indicadores prontos para os códigos que você mais vai tratar:

err.isAuthError: verdadeiro para auth_error
err.isRateLimited: verdadeiro para rate_limit
err.isNotFound: verdadeiro para not_found
err.isStateError: verdadeiro para state_error e conflict

Quando der, use esses indicadores em vez de comparar err.code como texto.

O que NÃO está nesta lista

Falhas só de HTTP (por exemplo, um 502 da Cloudflare antes de a requisição chegar até nós): não têm code, porque nunca chegaram à aplicação.
Erros do lado da plataforma que repassamos sem transformar: veja details.upstream em upstream_error.

Se você encontrar um código que não está nesta tabela, abra uma issue com o corpo da resposta: a tabela é a fonte da verdade, mas o produto pode já devolver um código novo que ainda não chegou à documentação.