Toda vez que você chama a API, ela devolve duas coisas: um código de status (um número que resume o que aconteceu) e um corpo (os dados ou a explicação do problema). Saber ler esses dois é o que separa uma integração que "às vezes falha misteriosamente" de uma que se recupera sozinha.

Esta página responde três perguntas práticas: como vem uma resposta de sucesso, como vem um erro, e o que fazer diante de cada código. As mensagens de erro do GS Engage já chegam em português — a ideia é você reaproveitá-las direto para quem for corrigir.

Aqui está a pegadinha que mais confunde quem começa: nem toda listagem responde no mesmo formato. Existem dois, e você precisa saber qual esperar de cada endpoint, senão seu código procura data onde só tem uma lista solta.

Formato 1 — paginado: { data, meta }

É o formato da maioria das listagens. Os itens vêm dentro de data, e um bloco meta te conta quantos existem no total e quantas páginas há. Você usa isso para saber quando parar de pedir.

{
  "data": [
    { "id": "507f1f77bcf86cd799439011", "name": "Maria Silva" },
    { "id": "507f1f77bcf86cd799439012", "name": "João Pereira" }
  ],
  "meta": {
    "limit": 20,
    "count": 20,
    "total": 137,
    "page": 1,
    "totalPages": 7
  }
}

O que isso significa para você: há 137 leads no total (total), distribuídos em 7 páginas (totalPages). Você está na página 1 e recebeu 20 itens. Peça a página 2 com ?page=2 e siga até chegar em totalPages.

Respondem neste formato paginado, por exemplo: GET /api/v1/leads, GET /api/v1/routines, GET /api/v1/prospections, GET /api/v1/conversations/threads e as demais listagens.

Formato 2 — data sem meta

Um endpoint foge à paginação: GET /api/v1/webhooks devolve a lista em data, mas sem o bloco meta (retorna todos os webhooks do projeto de uma vez, sem paginar).

{
  "data": [
    { "id": "507f1f77bcf86cd799439021", "name": "Webhook CRM", "url": "https://..." }
  ]
}

// Paginado: itens em .data, com .meta
const leadsRes = await fetch(`${BASE}/leads?apiKey=${apiKey}`);
const { data: leads, meta } = await leadsRes.json();
console.log(`${leads.length} de ${meta.total} leads`);

// Webhooks: itens em .data, mas SEM .meta (sem paginação)
const whRes = await fetch(`${BASE}/webhooks?apiKey=${apiKey}`);
const { data: webhooks } = await whRes.json();
console.log(`${webhooks.length} webhooks`);

# Paginado: itens em ["data"], com ["meta"]
leads_res = requests.get(f"{BASE}/leads", params={"apiKey": api_key})
body = leads_res.json()
leads, meta = body["data"], body["meta"]
print(f"{len(leads)} de {meta['total']} leads")

# Webhooks: itens em ["data"], mas SEM ["meta"]
wh_res = requests.get(f"{BASE}/webhooks", params={"apiKey": api_key})
webhooks = wh_res.json()["data"]
print(f"{len(webhooks)} webhooks")

Quando algo dá errado, o código de status não é 200. O corpo muda de cara: em vez de dados, você recebe uma explicação. O caso mais rico é o 400 (Bad Request), que detalha campo por campo o que precisa ser ajustado.

O envelope de erro

Todo erro da API vem embrulhado num objeto error — nunca na raiz do corpo. Dentro dele há sempre um message (o resumo, em português) e, no caso do 400, uma lista errors detalhando campo por campo.

{
  "error": {
    "message": "Não foi possível criar o lead.",
    "errors": [
      { "field": ["emails"], "message": "É obrigatório informar ao menos um contato." },
      { "field": ["customFields", "orcamento"], "message": "Campo personalizado não encontrado neste projeto." }
    ]
  }
}

Cada item de errors tem duas partes:

Estes são os quatro códigos de erro que você vai encontrar na prática. Para cada um: o que ele significa, a causa mais comum e o que fazer.

O caso do 429: respeite o Retry-After

O 429 é o único erro que não é culpa dos seus dados — é só ritmo. O corpo segue o mesmo envelope ({ "error": { "message": "Limite de requisições excedido..." } }), mas o que importa aqui são os cabeçalhos HTTP que acompanham a resposta:

Retry-After: 12
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1700000000

O que fazer: espere os segundos indicados em Retry-After (aqui, 12s) antes de tentar de novo. Se falhar outra vez, dobre a espera — isso é backoff exponencial (espera crescente a cada tentativa). Nunca fique martelando a API em loop apertado; você só prolonga o bloqueio.

Vamos juntar tudo. O gatilho abaixo é o mais comum: tentar criar um lead sem nenhum contato. A API recusa com 400 e explica exatamente o que faltou. O código lê a lista errors e mostra cada problema já em português.

const res = await fetch(`${BASE}/leads?apiKey=${apiKey}`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Lead sem contato" }), // falta emails/phones/mobiles
});

if (!res.ok) {
  const { error } = await res.json(); // tudo vem dentro de "error"

  if (res.status === 400) {
    console.error(`O que houve: ${error.message}`);
    // Percorre cada campo com problema — a message já vem em pt-BR.
    // field é uma lista (caminho) — junte com ponto para exibir.
    for (const e of error.errors ?? []) {
      console.error(`  • ${e.field.join(".")}: ${e.message}`);
    }
  } else if (res.status === 401) {
    console.error("apiKey ausente ou inválida — confira sua chave.");
  } else if (res.status === 429) {
    const wait = Number(res.headers.get("Retry-After") || 5);
    console.warn(`Limite atingido — aguarde ${wait}s e tente de novo.`);
  }
}

res = requests.post(
    f"{BASE}/leads",
    params={"apiKey": api_key},
    json={"name": "Lead sem contato"},  # falta emails/phones/mobiles
)

if not res.ok:
    error = res.json().get("error", {})  # tudo vem dentro de "error"

    if res.status_code == 400:
        print(f"O que houve: {error.get('message')}")
        # Percorre cada campo com problema — a message já vem em pt-BR.
        # field é uma lista (caminho) — junte com ponto para exibir.
        for e in error.get("errors", []):
            print(f"  • {'.'.join(map(str, e['field']))}: {e['message']}")
    elif res.status_code == 401:
        print("apiKey ausente ou inválida — confira sua chave.")
    elif res.status_code == 429:
        wait = int(res.headers.get("Retry-After", "5"))
        print(f"Limite atingido — aguarde {wait}s e tente de novo.")

Rodando o exemplo acima, a saída seria algo assim:

O que houve: Não foi possível criar o lead.
  • emails: É obrigatório informar ao menos um contato.

O que isso significa para o negócio: você sabe na hora que o lead não entrou porque veio sem forma de contato — e a mensagem em português já pode ir direto para quem preencheu a origem dos dados.