Erros da API
O formato dos erros da API da XBASE, o que cada status HTTP quer dizer e a lista de códigos estáveis para a sua integração tratar.
Atualizado em
Toda resposta de erro da API tem o mesmo formato. Trate o erro pelo status HTTP e pelo code: o texto de message explica o problema, mas pode mudar.
Formato
{
"statusCode": 401,
"timestamp": "2026-11-04T16:03:56.074Z",
"path": "/api/external/v1/me",
"method": "GET",
"message": "Chave de API inválida ou revogada.",
"code": "INVALID_API_KEY"
}| Campo | Descrição |
|---|---|
statusCode | Status HTTP |
message | O que deu errado, em texto |
code | Código estável do erro. Erros de validação (400) não têm code |
details | Dados extras de alguns erros, como details.gupshupCode |
timestamp · path · method | Quando e em qual rota |
Status HTTP
| Status | Quer dizer |
|---|---|
| 200 · 204 | Deu certo (204 não tem corpo) |
| 400 | Requisição inválida: campo faltando ou fora da regra. A message lista os campos |
| 401 | Chave ausente, inválida ou revogada |
| 403 | A chave não tem o escopo da rota |
| 404 | O recurso não existe neste workspace |
| 422 | A Meta ou a Gupshup recusou, ou o recurso não está pronto para a ação |
| 5xx | Erro na XBASE. Tente de novo depois de alguns segundos |
Códigos
code | Status | Quando |
|---|---|---|
INVALID_API_KEY | 401 | Sem cabeçalho Authorization, chave em formato errado, inexistente ou revogada |
MISSING_SCOPE | 403 | A chave não tem o escopo da rota |
CONNECTION_NOT_FOUND | 404 | O app de WhatsApp não existe neste workspace |
SOURCE_MISMATCH | 400 | source não é o número do app |
CONNECTION_NOT_CONFIGURED | 422 | O número de WhatsApp está sem número de origem ou sem a credencial da Gupshup |
GUPSHUP_ERROR | 422 | A Gupshup recusou o envio do template |
NOT_FOUND | 404 | A conta do Instagram (connectionId) não é deste workspace |
META_ERROR | 422 | A Meta recusou a ação no Instagram |
Boas práticas
- Trate pelo
codee pelo status, não pelo texto demessage. - Em
5xx, tente de novo com espera crescente (por exemplo, 2, 10 e 30 segundos). - Não repita um envio de WhatsApp que voltou
200: o contato já recebeu. A API não evita envio duplicado. - Em
401, confira se a chave não foi revogada em Integrações → Chaves de API.
Perguntas frequentes
Veja também
Revisão das respostas de um agente externo
Peça à XBASE para revisar a resposta de um agente externo antes de enviá-la ao contato, com os guardrails de saída configurados no agente.
Use a XBASE pelo Claude, pelo Cursor e por outros agentes
Conecte agentes de IA como o Claude Code e o Cursor ao seu workspace da XBASE pelo MCP.