Skip to main content
The /api/ctai endpoint can return errors in two ways:
  • Before the stream opens — as an application/json response with an HTTP error status code (400, 429, 500).
  • Inside the stream — as an error SSE event with a JSON payload. See SSE Events.

​
HTTP error responses

​
400 — Bad request

Returned when the request cannot be processed due to a client error.
The ioc query parameter was not provided.
{ "error": "Falta el parámetro de IoC" }
The ioc value does not match any supported format: IPv4, IPv6, domain, MD5, SHA1, or SHA256.
{ "error": "Tipo de IoC desconocido" }

​
429 — Too many requests

Returned when the requesting IP has exceeded the rate limit. See Rate Limiting. 
{ "error": "Too many requests", "retryAfterSeconds": 12 }
FieldTypeDescription
errorstringAlways "Too many requests".
retryAfterSecondsnumberSeconds to wait before the next request will succeed.
The response also includes these headers:
HeaderDescription
Retry-AfterSame value as retryAfterSeconds.
X-RateLimit-LimitMaximum requests allowed in the window.
X-RateLimit-WindowWindow duration in seconds.

​
500 — Internal server error

Returned when an unexpected error occurs before the stream can be opened — for example, when all CTI sources fail critically. 
{
  "error": "No se pudo completar la consulta de fuentes del IoC.",
  "stage": "ioc",
  "errorType": "unknown"
}

​
Stream error events

Errors that occur after the stream has opened are delivered as error SSE events instead of an HTTP error status. The stream closes immediately after an error event. 
{
  "error": "La API Key de OpenRouter no es válida o no tiene permisos suficientes.",
  "stage": "ai",
  "errorType": "invalid_api_key"
}
FieldTypeDescription
errorstringHuman-readable error message in Spanish.
stagestringPipeline stage where the error occurred. See stages below.
errorTypestringMachine-readable error classification. See error types below.

​
Stage values

The stage field identifies which part of the analysis pipeline failed.
The error occurred while fetching data from one or more CTI sources (VirusTotal, AbuseIPDB, PolySwarm, Robtex). The AI analysis was not attempted.Example:
{
  "error": "No se pudo completar la consulta de fuentes del IoC.",
  "stage": "ioc",
  "errorType": "unknown"
}
The error occurred while calling OpenRouter or processing the AI model’s response.Example:
{
  "error": "La API Key de OpenRouter no es válida o no tiene permisos suficientes.",
  "stage": "ai",
  "errorType": "invalid_api_key"
}
An error occurred that could not be attributed to a specific stage.
{
  "error": "No se pudo completar el análisis.",
  "stage": "unknown"
}

​
Error type values

The errorType field provides a machine-readable classification for programmatic error handling. It appears in both HTTP error response bodies and in error SSE event payloads, as well as in warnings[].reason within meta events.
errorTypeDescription
invalid_api_keyThe API key for a provider is missing, invalid, or does not have sufficient permissions.
model_errorThe AI model returned an unexpected error — for example, a context length limit was exceeded.
api_unavailableThe provider’s service is temporarily unavailable (HTTP 5xx from upstream).
not_foundThe IoC was not found in the provider’s records.
unknownAn unexpected error with no more specific classification.

​
Common error bodies

// Invalid OpenRouter API key
{
  "error": "La API Key de OpenRouter no es válida o no tiene permisos suficientes.",
  "stage": "ai",
  "errorType": "invalid_api_key"
}

// AI model returned an error
{
  "error": "El modelo devolvió un error inesperado durante el análisis.",
  "stage": "ai",
  "errorType": "model_error"
}

// Provider service unavailable
{
  "error": "La API de VirusTotal no está disponible en este momento.",
  "stage": "ioc",
  "errorType": "api_unavailable"
}

// IoC not found in provider records
{
  "error": "El IoC no existe en los registros de PolySwarm.",
  "stage": "ioc",
  "errorType": "not_found"
}

// Generic IoC stage failure
{
  "error": "No se pudo completar la consulta de fuentes del IoC.",
  "stage": "ioc",
  "errorType": "unknown"
}
Non-fatal source failures — where some sources succeed and others fail — are reported as warnings in the meta SSE event rather than as errors. The stream continues and the AI analysis proceeds with data from the available sources.

Build docs developers (and LLMs) love

Get started for freeTalk to us