FlowOrdr — Asistente IA con RAG para tu negocio

Errores HTTP #

Códigos y cuerpos que producen los controladores y middlewares de la API.

La API devuelve varios formatos reales: ProblemDetails usa title, status y detail; el widget usa error/details; algunos endpoints usan code/message. Un 401 del middleware de autenticación puede venir sin JSON.

HTTP	Cuándo ocurre	Cómo resolverlo
400	Body inválido, archivo vacío o formato no admitido.	Comprueba los campos requeridos y usa un formato de archivo admitido.
401	Clave o sesión de widget inválida; también puede ser un desafío de autenticación sin body.	Verifica la clave o renueva la sesión. Para API key, envía X-Api-Key.
402	Suscripción expirada, suspendida o cancelada tras el periodo de gracia.	Reactiva la suscripción o cambia de plan desde tu cuenta.
403	El dominio del widget no está autorizado o la clave no tiene permisos para el recurso.	Agrega el dominio permitido en la configuración del widget o usa una clave con acceso.
404	Documento o conversación ausente dentro del tenant.	Confirma el ID y que pertenezca al tenant de la clave.
409	Intentas borrar un documento usado por un canal.	Desvincula el documento de los canales indicados y vuelve a intentar.
413	Avatar de widget mayor a 1 MiB.	Reduce el avatar a 1 MiB o menos. El límite de documentos depende del plan y devuelve 429 si se agota.
422	Validación de checkout de cuenta, por ejemplo interval no admitido.	Usa monthly o annual. En chat y documentos, los cuerpos inválidos devuelven 400.
429	Límite de peticiones, mensajes mensuales, documentos o almacenamiento.	Espera retry_after antes de repetir; si es cupo mensual, consulta /api/v2/documents/tenant-usage y tu plan.
500	Fallo inesperado del servicio.	Reintenta con el identificador del incidente y contacta soporte si persiste.
502	No se pudo guardar el avatar del widget.	Reintenta más tarde.
503	LLM, base vectorial o almacenamiento temporalmente indisponible.	Reintenta con espera gradual.
504	Timeout al buscar, generar o procesar una carga.	Reintenta; reduce el tamaño o complejidad de la petición si se repite.

HTTP 400

Ejemplo 400

{
  "title": "Bad Request",
  "status": 400,
  "detail": "No se proporcionó archivo o el archivo está vacío"
}

HTTP 401

Ejemplo 401

{
  "error": "invalid_widget_key",
  "details": "Widget key is invalid or inactive"
}

HTTP 402

Ejemplo 402

{
  "error": "Subscription required",
  "detail": "Your trial or subscription has expired. Please subscribe to continue.",
  "subscriptionStatus": "Expired",
  "upgradeUrl": "https://flowordr.com/pricing"
}

HTTP 403

Ejemplo 403

{
  "error": "origin_not_allowed",
  "details": "This widget key is not authorized for this domain"
}

HTTP 404

Ejemplo 404

{
  "title": "Not Found",
  "status": 404,
  "detail": "Documento 123 no encontrado"
}

HTTP 409

Ejemplo 409

{
  "title": "Documento en uso",
  "status": 409,
  "detail": "El documento está en uso por un canal",
  "documentId": 123,
  "channels": {
    "widgets": [],
    "telegram": [],
    "whatsapp": []
  }
}

HTTP 413

Ejemplo 413

{
  "code": "too_large",
  "message": "El archivo supera 1 MB."
}

HTTP 422

Ejemplo 422

{
  "code": "checkout.invalid_interval",
  "message": "Interval debe ser 'monthly' o 'annual'."
}

HTTP 429

Ejemplo 429

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Limit: 100 requests per 60 seconds",
  "retry_after": 60
}

HTTP 500

Ejemplo 500

{
  "title": "Internal Server Error",
  "status": 500,
  "detail": "Error al procesar el documento"
}

HTTP 502

Ejemplo 502

{
  "code": "storage_error",
  "message": "No pudimos guardar la imagen. Inténtalo de nuevo."
}

HTTP 503

Ejemplo 503

{
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Storage or processing service unavailable"
}

HTTP 504

Ejemplo 504

{
  "title": "Request Timeout",
  "status": 504,
  "detail": "Request timed out while generating answer"
}

Variantes de 429

El cupo mensual de chat sin streaming devuelve ProblemDetails; antes de abrir SSE, streaming devuelve otro JSON. El widget usa error y details.

Chat 429

{"title":"monthly_limit_reached","status":429,"detail":"Se alcanzó el límite mensual"}

Streaming 429

{"error":"monthly_limit_reached","details":"Se alcanzó el límite mensual"}

Widget 429

{"error":"rate_limit_exceeded","details":"Too many requests. Please try again later."}

La documentación anterior atribuía 422 a cualquier body inválido. Chat y documentos devuelven 400 en ese caso; 422 corresponde a validaciones específicas como checkout. ASP.NET Core también puede rechazar una petición antes de entrar al controlador por formato o autenticación.