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 contará como sucesso, será faturado como sucesso e aparecerá no seu feed de Activity junto com os seus 200s.

Isso parece pequeno. Isso muda como você mede a precisão de scraping em escala.

Como funciona

Cada request para a FourA recebe um de sete resultados que decidem o faturamento e a análise. Apenas success é faturável. O restante é dividido por quem é o responsável 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 que você enviou estava malformada
service_fail, service_error e rate_limit quando algo do nosso lado bloqueou a request

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

Agora o seu bloco validate decide. A request executa suas regras durante a execução. Se a response as satisfizer, o resultado é success.

curl -X POST "https://eu.api.foura.ai/v1/request" \
  -H "Authorization: Bearer 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 corpo contiver um marcador de CAPTCHA ou uma string de acesso negado, a request falha. Qualquer outra coisa é success.

Duas regras para lembrar:

Sem o validate, o comportamento não muda. Requests que não declaram validação ainda são faturadas apenas no HTTP 200. Você escolhe aderir.
O validate funciona nos dois sentidos. Regras de aceitação aprovam; regras de falha rejeitam. Elas se compõem. Assim, você pode aceitar [200, 403] e ainda falhar quando o corpo contiver o conteúdo incorreto.

Impacto

A mudança é mais importante para equipes cujos alvos retornam responses não-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 (ainda são dados úteis, ainda vale a pena registrar como sucesso)
Endpoints de busca de e-commerce que retornam 404 quando um SKU está fora de estoque (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 faziam seu próprio controle por cima dos 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 adivinhamos. Seus totais faturados correspondem ao que você mesmo contaria (resultados iniciais: a mudança se aplica apenas daqui para frente, então as linhas de Activity mais antigas mantêm sua classificação original).

O efeito prático em um job de scraping: menos etapas de reconciliação entre o seu pipeline e a nossa fatura. Se você já realizava a validação no corpo da response após o recebimento, pode mover esse contrato para a própria request e parar de manter um conjunto paralelo de regras de aprovação/falha fora da nossa API. Uma única definição se uma request mereceu seu lugar no seu conjunto de dados, em vez de duas que divergiam.

Mas mantivemos a rede de segurança. Se você não passar um bloco validate, nada muda. O classificador recorre ao padrão "200 significa sucesso", de modo que as requests que funcionavam ontem funcionam da mesma maneira hoje.

Para usuários avançados

O validate aceita três conjuntos de regras que funcionam 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 "Authorization: Bearer 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 exige:

O status seja 200 ou 304
A response anuncie um content type JSON
O corpo contenha um campo de preço
O corpo não contenha um aviso de manutenção ou uma armadilha de CAPTCHA

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

Combinado com followRedirects: siga até cinco saltos e depois valide a response final. Um redirecionamento enganoso de uma URL limpa para um portal de CAPTCHA falha de forma limpa, em vez de poluir seu conjunto de dados.

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

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

Próximos passos

Estamos trabalhando em primitivas de regras mais ricas: correspondências de regex para data, predicados JSON-path estruturados e correspondência de header mais flexível. O princípio continua o mesmo. Você declara como deve ser o sucesso; a API o respeita 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 de acordo com as regras que você mesmo escreveu, esse será um número em que você realmente poderá confiar.