Erros e códigos de status

A API do finlight usa códigos de status HTTP convencionais para sinalizar o resultado de uma requisição. Um status 2xx significa sucesso; 4xx significa que a requisição foi rejeitada (geralmente algo que você pode corrigir); 5xx significa um problema do nosso lado. Cada erro retorna um corpo JSON descrevendo o que deu errado.

Observação: As requisições REST e WebSocket se autenticam com o cabeçalho X-API-KEY. Uma chave ausente ou inválida retorna 401. (A autenticação de entrega de webhooks — os cabeçalhos que o finlight envia ao seu endpoint — é separada; consulte Autenticação de webhooks.)

Códigos de status em resumo

400 — Bad Request

Retornado quando os parâmetros de consulta ou o corpo da requisição falham na validação, ou quando a string query usa uma sintaxe de nível de campo inválida.

Parâmetro inválido:

{
  "statusCode": 400,
  "message": ["pageSize must not be greater than 100"],
  "error": "Bad Request"
}

Sintaxe de query inválida (POST /v2/articles):

{
  "statusCode": 400,
  "message": [
    {
      "property": "query",
      "constraints": { "query": "Invalid query syntax near 'ticker:'" }
    }
  ],
  "error": "Bad Request"
}

Consulte Criação de consultas avançadas para a sintaxe correta de query.

401 — Unauthorized

O cabeçalho X-API-KEY está ausente, malformado ou não é uma chave válida.

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Obtenha ou rotacione sua chave no painel do finlight.

403 — Forbidden

A requisição está autenticada, mas seu plano não inclui a capacidade solicitada — por exemplo, solicitar o conteúdo completo do artigo em um plano que não o inclui.

{
  "statusCode": 403,
  "message": "Your subscription does not allow calling the extended article content"
}

Consulte Limites de taxa e cotas para ver quais capacidades cada plano inclui.

404 — Not Found

O recurso solicitado não existe — o caso mais comum é GET /v2/articles/by-link com um link que o finlight não indexou.

{
  "statusCode": 404,
  "message": "Article not found"
}

422 — Unprocessable Entity

Alguns endpoints validam através do validador global, que retorna um mapa de erros indexado por campo. Cada chave é o campo problemático; o valor lista as restrições que falharam.

{
  "status": 422,
  "errors": {
    "language": "language must be a string"
  }
}

Observação: Falhas de validação podem aparecer como 400 (nos endpoints de artigos) ou 422 (validador global), dependendo da rota — ambos indicam uma requisição malformada. Inspecione o corpo para ver qual campo falhou.

429 — Too Many Requests

Você excedeu um limite de uso. Há dois casos distintos, cada um com uma mensagem específica:

Cota mensal de requisições excedida:

{
  "statusCode": 429,
  "message": "Throttling Exception: Exceeded token limit of 5000 for the current period."
}

Taxa de pico (curto prazo) excedida:

{
  "statusCode": 429,
  "message": "Throttling Exception: Exceeded rate limit of 10 requests per 10 seconds."
}

Observação: O finlight atualmente não retorna cabeçalhos Retry-After ou de limite de taxa. Para um 429 de pico, recue e tente novamente após ~10 segundos. Para um 429 de cota mensal, as requisições voltarão a funcionar no início do seu próximo período de cobrança (ou após um upgrade). Consulte Limites de taxa e cotas.

500 — Internal Server Error

Ocorreu um erro inesperado do lado do finlight. Eles são transitórios — tente novamente com recuo (backoff) e, se persistir, fale conosco pelo Suporte.

{
  "statusCode": 500,
  "message": "Internal server error"
}

Como lidar bem com os erros

• Verifique sempre primeiro o código de status e depois leia o corpo JSON para os detalhes.
• Os 4xx (exceto 429) são seu bug — corrija a requisição; tentar de novo sem alterações não ajudará.
• 429 e 5xx podem ser repetidos — use recuo exponencial. Para um 429 de pico, ~10 s é suficiente.
• Erros de WebSocket chegam como uma mensagem de servidor error no socket, em vez de um status HTTP — consulte Conceitos básicos do WebSocket.
• Falhas de entrega de webhooks (ao seu endpoint) são registradas no painel, não retornadas a você de forma síncrona — consulte Testando webhooks.