Errores y códigos de estado

La API de finlight usa códigos de estado HTTP convencionales para indicar el resultado de una solicitud. Un estado 2xx significa éxito; 4xx significa que la solicitud fue rechazada (normalmente algo que puedes corregir); 5xx significa un problema de nuestro lado. Cada error devuelve un cuerpo JSON que describe qué salió mal.

Nota: Las solicitudes REST y WebSocket se autentican con el encabezado X-API-KEY. Una clave faltante o inválida devuelve 401. (La autenticación de entrega de webhooks —los encabezados que finlight envía a tu endpoint— es independiente; consulta Autenticación de webhooks.)

Códigos de estado de un vistazo

400 — Bad Request

Se devuelve cuando los parámetros de consulta o el cuerpo de la solicitud no superan la validación, o cuando la cadena query usa una sintaxis de nivel de campo inválida.

Parámetro inválido:

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

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

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

Consulta Creación de consultas avanzadas para la sintaxis correcta de query.

401 — Unauthorized

El encabezado X-API-KEY falta, está malformado o no es una clave válida.

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

Obtén o rota tu clave en el panel de finlight.

403 — Forbidden

La solicitud está autenticada, pero tu plan no incluye la capacidad solicitada; por ejemplo, solicitar el contenido completo del artículo en un plan que no lo incluye.

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

Consulta Límites de tasa y cuotas para ver qué capacidades incluye cada plan.

404 — Not Found

El recurso solicitado no existe; lo más común es GET /v2/articles/by-link con un link que finlight no ha indexado.

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

422 — Unprocessable Entity

Algunos endpoints validan mediante el validador global, que devuelve un mapa de errores indexado por campo. Cada clave es el campo problemático; el valor enumera las restricciones que fallaron.

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

Nota: Los fallos de validación pueden aparecer como 400 (en los endpoints de artículos) o 422 (validador global), según la ruta; ambos indican una solicitud malformada. Inspecciona el cuerpo para ver qué campo falló.

429 — Too Many Requests

Has superado un límite de uso. Hay dos casos distintos, cada uno con un mensaje específico:

Cuota mensual de solicitudes superada:

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

Tasa de ráfaga (a corto plazo) superada:

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

Nota: finlight no devuelve actualmente encabezados Retry-After ni de límite de tasa. Para un 429 de ráfaga, espera y reintenta tras ~10 segundos. Para un 429 de cuota mensual, las solicitudes volverán a funcionar al inicio de tu siguiente período de facturación (o tras una mejora de plan). Consulta Límites de tasa y cuotas.

500 — Internal Server Error

Ocurrió un error inesperado del lado de finlight. Son transitorios: reintenta con retroceso (backoff) y, si persiste, contáctanos a través de Soporte.

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

Cómo manejar bien los errores

• Comprueba siempre primero el código de estado y luego lee el cuerpo JSON para los detalles.
• Los 4xx (excepto 429) son tu error: corrige la solicitud; reintentarla sin cambios no ayudará.
• 429 y 5xx se pueden reintentar: usa retroceso exponencial. Para un 429 de ráfaga, ~10 s es suficiente.
• Los errores de WebSocket llegan como un mensaje de servidor error en el socket en lugar de un estado HTTP; consulta Conceptos básicos de WebSocket.
• Los fallos de entrega de webhooks (a tu endpoint) se registran en el panel, no se te devuelven de forma síncrona; consulta Pruebas de webhooks.