Synergy Connect

Documentação

EntrarCriar conta

Erros

Há dois formatos, conforme a rota.

Formato da Graph API#

Envio, mídia, handoff e token de Flow respondem como a Graph API da Meta:

code é o que a integração deve usar para decidir. Erros da própria Synergy trazem fbtrace_id começando com syn- e, às vezes, error_data.details (em inglês). Quando a Meta recusa, o erro dela é repassado com o status e o corpo que ela mandou (por exemplo 400 com o código 131047, fora da janela de 24 h).

JSON
{
  "error": {
    "message": "(#190) Invalid OAuth access token.",
    "type": "OAuthException",
    "code": 190,
    "fbtrace_id": "syn-3f9a1c0b"
  }
}

Formato da gestão de webhooks#

/v1/webhooks… responde { "error": "…" }, às vezes com issues (problemas de validação, no formato do zod) ou feature (a feature do plano que falta):

A mensagem mistura inglês (recusas da rota) e português (regras da organização e do plano). Decida pelo status HTTP, não pelo texto.

JSON
{ "error": "Invalid body", "issues": [{ "code": "invalid_type", "path": ["fields"], "message": "Invalid input: expected array, received undefined" }] }

Tabela de códigos#

HTTPcodeO que éO que fazer
400100Parâmetro inválido: falta to, corpo que não é JSON de objeto, corpo acima de 64 KB, falta phone_number_id na queryCorrija a requisição; veja error_data.details. Não repita igual
4001390009Flow com endpoint da Synergy sem flow_token válidoEmita o token (WhatsApp Flows)
401190Chave ausente, malformada, revogada ou sem acesso ao númeroConfira o header e a chave; crie outra se foi revogada
403200A chave não tem o escopo exigidoEdite a chave no app ou use outra
4031390004O plano não inclui a APIMude o plano em Configurações → Plano e uso
4031390005Conta em modo leitura ou suspensa por falta de pagamentoRegularize em Configurações → Cobrança
4031390007O plano não inclui WhatsApp FlowsMude o plano
404100O phone_number_id ou o objeto não existe para esta chaveConfira o id; a resposta não diz o que o id é
4091390001Chave bot e a conversa está com um atendenteEspere a conversa voltar para a automação
4091390002Um envio com a mesma Idempotency-Key ainda está em andamentoEspere e repita com a mesma chave
4091390016POST …/journeys/{journey_id}/runs para uma pessoa que já tem uma execução de Jornada em andamento (uma chave nova não muda isso)Espere a Jornada atual do contato terminar
4091390008O Flow usa o endpoint de outro provedor, ou não pode ser enviadoUse outro Flow
4221390003Idempotency-Key já usada para outro destinatárioUse uma chave nova
429130429Limite de taxaEspere Retry-After (Limites de taxa)
4291390006Volume do ciclo esgotadoCompre uma recarga, mude o plano ou espere o ciclo; details traz o link
4291390010Limite de envios de Flow do plano no ciclo (sem Retry-After)Aguarde o ciclo ou mude o plano
5032Falha temporária (a Meta não respondeu ou algo inesperado)Tente de novo com backoff
outro—Erro da Meta, repassadoVeja a documentação da Meta para o código

Erros da gestão de webhooks#

HTTPQuandoO que fazer
400Invalid body; URL não aceita; a URL não respondeu à verificação em 5 s; chave limitada a números; limite de 20 webhooksLeia error e issues
401Chave revogada ou desconhecida (Invalid or revoked key); chave malformada vem no formato da Graph API (190)Confira a chave
403Sem o escopo management; plano sem API (feature: "api"); conta em modo leituraEdite a chave ou o plano
404Webhook not foundConfira o hook_id
409Replay de um webhook desativadoReative com PATCH {"enabled": true}
413Corpo acima de 16 KBReduza o corpo
429Rate limit hit (30 por minuto por chave)Espere Retry-After
502POST /v1/webhooks/{hook_id}/test: a URL não aceitou o testeVeja HTTP <status> ou timeout no error

Exemplo: tratar a resposta#

Exemplo

curl

curl -s -o resposta.json -w '%{http_code}\n' -X POST \
  'https://api.synergyconnect.com.br/v25.0/106540352242922/messages' \
  -H "Authorization: Bearer $SYNERGY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"messaging_product":"whatsapp","type":"text","text":{"body":"oi"}}'
cat resposta.json   # 400, code 100, details: The parameter "to" is required.

JavaScript

const res = await fetch(url, { method: 'POST', headers, body });
const data = await res.json();
if (!res.ok) {
  const { code, message, error_data } = data.error ?? {};
  if (res.status === 429) {
    // veja rate-limits.md
  } else if (res.status >= 500) {
    // falha temporária: tente de novo com backoff
  } else {
    throw new Error(`#${code} ${message} ${error_data?.details ?? ''}`);
  }
}

Python

res = requests.post(url, headers=headers, json=body)
if not res.ok:
    err = res.json().get("error", {})
    if res.status_code == 429:
        pass  # veja rate-limits.md
    elif res.status_code >= 500:
        pass  # falha temporária: tente de novo com backoff
    else:
        raise RuntimeError(f"#{err.get('code')} {err.get('message')}")

Ficou com dúvida? Escreva para suporte@synergyconnect.com.br.