Pular para o conteúdo principal

Solução de problemas

A maioria dos problemas corresponde a um código de status HTTP. Primeiro examine a resposta com curl -i ou res.status e depois consulte os casos abaixo.

Está usando um assistente de IA pelo MCP? Consulte o guia de solução de problemas do MCP. Erros do MCP podem retornar HTTP 200 com um erro de JSON-RPC ou de ferramenta; as orientações abaixo são específicas da API REST.

401 Authentication Failed​

Você ativou uma chave de API na conexão, mas a requisição não a incluiu ou ela está incorreta. O Sheet Best usa o cabeçalho X-Api-Key, não Authorization.

curl -H 'X-Api-Key: YOUR_KEY' \
  'https://api.sheetbest.com/sheets/<id>'

Confira a chave em Connection → Advanced Settings (Conexão → Configurações avançadas). Consulte chaves de API.

402 Payment Required​

Você usou todas as requisições mensais do plano ou a operação não está disponível nele. Verifique X-RateLimit-Remaining em qualquer resposta: quando chega a 0, as requisições são bloqueadas até o próximo ciclo de cobrança. O código de erro retornado é throttle.

Faça upgrade do seu plano para continuar.

403 Forbidden / write_error​

As gravações (POST, PATCH, PUT, DELETE) exigem que o Sheet Best tenha acesso de edição à planilha do Google Sheets. Duas causas comuns:

  • A planilha está compartilhada como Leitor em vez de Editor (em conexões com “Qualquer pessoa com o link”).
  • Você usa uma conexão privada, mas a conta autorizada não tem mais acesso de edição.

Compartilhe a planilha novamente com permissão de edição ou reconecte-a pelo Connect with Drive.

404 Not Found​

  • O ID da conexão na URL está incorreto: copie-o novamente do painel.
  • O nome da aba foi digitado incorretamente: ele diferencia maiúsculas e minúsculas. Consulte abas.
  • O índice da linha não existe para essa operação.

405 Method Not Allowed​

O endpoint não aceita esse método. Casos comuns:

  • POST para /search: use GET com parâmetros de consulta.
  • GET em um endpoint de ação que só aceita gravações.

Consulte a referência de códigos de status HTTP.

Os números são retornados como strings​

Esse é o comportamento padrão. Adicione _raw=1 a qualquer requisição GET para receber tipos nativos:

curl 'https://api.sheetbest.com/sheets/<id>?_raw=1'

Consulte formatos de dados.

Array vazio no GET​

  • A planilha tem cabeçalhos, mas nenhuma linha de dados.
  • Os filtros na URL não encontraram correspondências: teste o endpoint sem filtros para confirmar que há linhas.
  • A aba consultada está incorreta: confira com /tabs/<TabName>.

Erros de CORS no navegador​

Se você ativou uma chave de API, chamar a API diretamente pelo navegador expõe a chave. O padrão recomendado é encaminhar as requisições pelo seu próprio backend e manter a chave no servidor.

Ainda precisa de ajuda?​