Fazer a sua primeira chamada
Autenticar um pedido à API Piloterr e ler a resposta.
Com a chave em mãos, a autenticação resume-se a um cabeçalho. Esta página mostra o formato de um pedido, como confirmar que funcionou e o que fazer quando não funciona.
Resposta
{
"remaining": 42180,
"total_used": 57820,
"renewal_date": "2026-04-01"
}Registros API
Enviar o pedido
Passe a sua chave no cabeçalho x-api-key em todas as chamadas. O endpoint de uso é gratuito, o que faz dele a forma mais segura de validar uma chave nova:
curl "https://api.piloterr.com/v2/usage" \
-H "x-api-key: $API_KEY"const res = await fetch("https://api.piloterr.com/v2/usage", {
headers: { "x-api-key": process.env.API_KEY },
})
if (!res.ok) throw new Error(`Request failed: ${res.status}`)
const usage = await res.json()Como é uma resposta de uso bem-sucedida
Um 200 do endpoint de uso significa que a chave funciona. O JSON inclui remaining (tempo de utilização combinado), os saldos subscription e credits, renewal_date quando se aplica um período, e a api_key que fez a chamada — incluindo as suas quotas. Essa chamada não consome créditos.
Se não funcionar
| Resposta | Causa | Correção |
|---|---|---|
401 Invalid API Key | O cabeçalho está em falta ou o valor está errado | Verifique se não copiou um espaço ou uma quebra de linha com o segredo |
401 Inactive API Key | A chave foi desativada | Reative-a em Chaves API ou crie uma nova |
401 Rate limit exceeded | Atingiu uma quota da chave ou o limite de taxa do seu plano | Abrande o ritmo ou aumente os limites da chave |
402 Payment required | Sem créditos disponíveis ou uma fatura por pagar | Compre uma recarga, ative a recarga automática ou regularize a fatura |
Defina o tempo limite do seu cliente HTTP para pelo menos 60 segundos. Muitas plataformas usam valores bem mais baixos por omissão e interrompem a chamada antes de o Piloterr responder.