Regras de validação agora decidem o que conta como sucesso

As regras de validate da sua request agora definem como cada resultado é classificado. Declare um 403 como aceitável, e um 403 entregue conta como sucesso, é faturado como sucesso e aparece no seu feed de Activity junto com os seus 200s.

Isso parece pequeno. Mas muda a forma como você mede a precisão da raspagem em escala.

Como funciona

Cada request para o FourA recebe um de sete resultados que definem o faturamento e a análise de dados. Apenas success é faturável. Os demais se dividem conforme a responsabilidade pela falha:

application_fail e application_error para quando o site de destino recusou ou retornou um corpo de erro
client_error quando a request enviada por você estava malformada
service_fail, service_error e rate_limit quando algo do nosso lado bloqueou a request

Antes dessa alteração, sucesso significava exatamente uma coisa: HTTP 200. Um 403 era sempre application_fail, mesmo que você soubesse que o 403 era a resposta esperada. (Algumas APIs de dados esportivos retornam 403 para mercados com restrição geográfica, e esse é o sinal que o seu código está aguardando.)

Agora, o seu bloco validate decide. A request executa as suas regras durante o processamento. Se a response atender a elas, o resultado é success.

curl -X POST "https://eu.api.foura.ai/v1/request" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/api/feed",
    "unblocker": true,
    "validate": {
      "status": { "accept": [200, 403] },
      "data": { "fail": ["captcha", "Access Denied"] }
    }
  }'

Isso trata 200 e 403 como status codes válidos. Se o body contiver um marcador de página de verificação ou uma string de acesso negado, a request falha. Qualquer outra coisa é success.

Duas regras para lembrar:

Sem validate, o comportamento permanece inalterado. Requests que não declaram validação ainda são faturadas apenas com base no HTTP 200. Você escolhe ativar.
validate funciona em ambas as direções. Regras de aceite passam; regras de falha rejeitam. Elas se compõem. Portanto, você pode aceitar [200, 403] e ainda assim falhar quando o body contiver o conteúdo errado.

Impacto

A mudança é mais relevante para equipes cujos alvos retornam responses diferentes de 200 que elas realmente desejam.

Exemplos de requests que vemos diariamente:

APIs de dados esportivos que retornam 403 para mercados com restrição geográfica (dados ainda úteis, que ainda valem a pena registrar como sucesso)
Endpoints de busca de e-commerce que retornam 404 quando um SKU está esgotado (um sinal que seu código lê, não uma falha)
APIs de streaming e conteúdo parcial que retornam 206

Antes da mudança, essas equipes mantinham seu próprio controle paralelo sobre os nossos logs de Activity. Elas não podiam confiar na coluna outcome porque a definição de sucesso delas não correspondia à nossa. Elas eram faturadas com base em um número com o qual não se importavam de verdade.

Agora a coluna reflete a realidade. A aba Activity no seu Dashboard mostra o que você definiu como sucesso, não o que nós supomos. Seus totais faturados correspondem ao que você mesmo contabilizaria (resultados iniciais: a mudança se aplica apenas daqui em diante, portanto linhas antigas de Activity mantêm sua classificação original).

O efeito prático em um job de scraping: menos etapas de conciliação entre o seu pipeline e a nossa fatura. Se você já executava validação no body da response após o recebimento, pode mover esse contrato para dentro da própria request e parar de manter um conjunto paralelo de regras de aprovação/rejeição fora da nossa API. Uma única definição sobre se uma request conquistou seu lugar no seu dataset, em vez de duas conflitantes.

Mas mantivemos a rede de segurança. Se você não passar um bloco validate, nada muda. O classificador volta para o padrão "200 significa sucesso", de modo que requests que funcionavam ontem continuam funcionando da mesma forma hoje.

Para Usuários Avançados

validate aceita três conjuntos de regras que rodam de forma independente: status, headers e data. Cada um aceita listas opcionais de accept e fail.

curl -X POST "https://eu.api.foura.ai/v1/request" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/9876",
    "followRedirects": 5,
    "unblocker": true,
    "validate": {
      "status": { "accept": [200, 304] },
      "headers": { "accept": { "content-type": "application/json" } },
      "data": { "accept": ["\"price\":"], "fail": ["maintenance", "captcha"] }
    }
  }'

Isso requer:

O status ser 200 ou 304
A response declarar um content type JSON
O body conter um campo price
O body não conter um aviso de manutenção ou uma página de verificação

Se qualquer regra falhar, o resultado é application_fail. Se tudo passar, é success. O classificador roda dentro da própria request, então você economiza o round trip que uma etapa separada de validação custaria.

Combinado com followRedirects: siga até cinco saltos e depois valide a response final. Um redirecionamento enganoso de uma URL limpa para uma página de verificação falha de forma limpa, em vez de poluir seu dataset.

E uma dica prática de quem roda os próprios scrapers: declare padrões data.fail de forma agressiva. Um 200 OK com uma página de verificação dentro é o modo mais comum de falha silenciosa em sites protegidos. Trate o body como autoritativo, não o status code.

Para o schema completo, a referência da request lista cada campo validate e como cada um se compõe.

Próximos passos

Estamos trabalhando em primitivas de regras mais ricas: correspondência por regex para data, predicados estruturados de JSON-path e correspondência mais flexível de headers. O princípio continua o mesmo. Você declara como é o sucesso; a API respeita isso de ponta a ponta, desde a request até a sua fatura.

Quando seu scraper quebrar, ele deve deixar isso bem claro. E quando ele funcionar seguindo regras que você mesmo escreveu, esse é um número no qual você pode realmente confiar.