Erros e limites de taxa
Todos os endpoints do Watch-IP devolvem erros na mesma forma e aplicam limites de taxa da mesma maneira, independentemente do produto que está a chamar.
Forma da resposta de erro
Uma resposta não-2xx é sempre um objeto JSON com error (um código estável e legível por máquina) e message (uma descrição legível por humanos). error mantém-se constante entre versões da API; o texto de message pode mudar, por isso faça a correspondência em error, não em message.
Resposta de erro
{
"error": "invalid_ip",
"message": "\"999.999.999.999\" is not a valid IPv4 or IPv6 address."
}Códigos de estado comuns
O conjunto exato de códigos que um endpoint pode devolver está documentado na sua própria página de referência; estes são os partilhados por toda a API.
- 400
- Entrada mal formada — um endereço IP inválido, um lote vazio ou demasiado grande (POST /v1/lookup permite até 100 IPs), ou um campo obrigatório em falta.
- 401
- Chave de API em falta ou inválida.
- 403
- Tipo de chave errado para esta rota (uma chave publicável num endpoint de chave secreta, ou vice-versa), ou — apenas para GET /v1/geo e POST /v1/email/validate — um Origin/Referer que não consta da lista de origens permitidas da chave. Neste último caso, também não é definido qualquer cabeçalho CORS, pelo que o navegador bloqueia a resposta independentemente deste corpo.
- 422
- Entrada semanticamente válida que não pode ser processada — atualmente apenas POST /v1/risk/check, quando o IP fornecido não pode ser resolvido para uma localização.
- 429
- Limite de taxa excedido para a janela de um minuto atual.
Limites de taxa
Os limites de taxa são aplicados por conta de cliente numa janela fixa de um minuto, partilhada entre todos os endpoints que chamar, em vez de ser controlada por rota. O limite conta chamadas HTTP, não itens: POST /v1/lookup e POST /v1/email/batch contam como um único pedido, quer contenham 1 ou 100 entradas, tal como criar, consultar e transferir uma tarefa de lista de e-mails. Um 429 por limite de taxa (error: "rate_limit_exceeded") inclui um cabeçalho Retry-After com o número de segundos até a janela atual ser reposta — aguarde esse tempo e tente novamente.
Repetir pedidos com segurança
GET /v1/geo, GET /v1/lookup/{ip}, POST /v1/lookup, e POST /v1/email/validate são apenas de leitura e podem ser repetidos em segurança imediatamente após um erro de rede. POST /v1/risk/check atualiza uma base de referência armazenada por predefinição — passe primeiro commit:false se precisar de uma nova tentativa especulativa que não a deva alterar.