Referencia HTTP y Códigos de Estado

Documentación completa de todos los endpoints y códigos de respuesta de la API.

URL Base

https://api.arkangelai.com/v1

Endpoints Disponibles

Chat

Método	Endpoint	Descripción
POST	/chat	Enviar un mensaje y recibir respuesta
POST	/chat/stream	Enviar mensaje con streaming de respuesta

Conversaciones

Método	Endpoint	Descripción
GET	/conversations	Listar conversaciones
GET	/conversations/:id	Obtener una conversación
PATCH	/conversations/:id	Actualizar conversación
DELETE	/conversations/:id	Eliminar conversación
GET	/conversations/search	Buscar en conversaciones
GET	/conversations/:id/export	Exportar conversación

Archivos

Método	Endpoint	Descripción
POST	/files	Subir un archivo
GET	/files	Listar archivos
GET	/files/:id	Obtener información de archivo
DELETE	/files/:id	Eliminar archivo

Uso

Método	Endpoint	Descripción
GET	/usage	Obtener métricas de uso
GET	/usage/limits	Consultar límites
GET	/usage/endpoints	Uso por endpoint
GET	/usage/errors	Historial de errores
GET	/usage/export	Exportar datos de uso
POST	/usage/alerts	Configurar alertas

Límites de Velocidad

Todos los endpoints de la API aplican límites de velocidad para garantizar un uso justo y la estabilidad de la plataforma. Los límites se aplican por usuario (identificado por su clave API) usando una ventana deslizante.

Límites Predeterminados

Endpoint	Límite	Ventana
POST /chat	20 solicitudes	1 minuto
POST /chat/stream	20 solicitudes	1 minuto
GET /conversations, GET /conversations/:id	60 solicitudes	1 minuto
PATCH /conversations/:id, DELETE /conversations/:id	30 solicitudes	1 minuto
POST /files	30 solicitudes	1 minuto
GET /files, GET /files/:id, DELETE /files/:id	60 solicitudes	1 minuto
GET /conversations/:id/export, GET /usage/export	5 solicitudes	1 minuto
GET /usage, GET /usage/*	60 solicitudes	1 minuto

Respuesta de Límite de Velocidad

Cuando excedes un límite, la API devuelve un estado 429 Too Many Requests con los siguientes encabezados:

Encabezado	Descripción
X-RateLimit-Limit	Solicitudes máximas permitidas en la ventana actual
X-RateLimit-Remaining	Solicitudes restantes en la ventana actual
X-RateLimit-Reset	Timestamp Unix cuando la ventana se reinicia
Retry-After	Segundos a esperar antes de reintentar

Espera la duración especificada en Retry-After antes de enviar otra solicitud.

Códigos de Estado HTTP

Respuestas Exitosas (2xx)

Código	Nombre	Descripción
200	OK	Solicitud exitosa
201	Created	Recurso creado exitosamente
204	No Content	Solicitud exitosa sin contenido de respuesta

Errores del Cliente (4xx)

Código	Nombre	Descripción
400	Bad Request	Solicitud mal formada o parámetros inválidos
401	Unauthorized	Falta clave API o es inválida
403	Forbidden	Sin permisos para el recurso
404	Not Found	Recurso no encontrado
409	Conflict	Conflicto con el estado actual
422	Unprocessable Entity	Datos válidos pero no procesables
429	Too Many Requests	Límite de solicitudes excedido

Errores del Servidor (5xx)

Código	Nombre	Descripción
500	Internal Server Error	Error interno del servidor
502	Bad Gateway	Error de puerta de enlace
503	Service Unavailable	Servicio temporalmente no disponible
504	Gateway Timeout	Tiempo de espera agotado

Formato de Errores

Todas las respuestas de error siguen este formato:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "message": "La clave API proporcionada no es válida",
    "param": "authorization",
    "request_id": "req_abc123"
  }
}

Campos del Error

Campo	Tipo	Descripción
type	string	Categoría del error
code	string	Código específico del error
message	string	Descripción legible del error
param	string	Parámetro que causó el error (si aplica)
request_id	string	ID único para seguimiento

Tipos de Error

Tipo	Descripción
invalid_request_error	Parámetros inválidos o faltantes
authentication_error	Problemas de autenticación
permission_error	Sin permisos necesarios
not_found_error	Recurso no existe
rate_limit_error	Límite de solicitudes excedido
api_error	Error interno de la API

Códigos de Error Comunes

Autenticación

Código	Descripción
invalid_api_key	Clave API inválida
missing_api_key	No se proporcionó clave API
api_key_revoked	Clave API revocada
api_key_expired	Clave API expirada

Solicitudes

Código	Descripción
invalid_message	Mensaje vacío o inválido
message_too_long	Mensaje excede límite de caracteres
invalid_conversation_id	ID de conversación inválido
invalid_file_id	ID de archivo inválido

Archivos

Código	Descripción
invalid_file_type	Tipo de archivo no soportado
file_too_large	Archivo excede tamaño máximo
file_processing_failed	Error al procesar archivo

Límites

Código	Descripción
rate_limit_exceeded	Límite de solicitudes por segundo
daily_limit_exceeded	Límite diario alcanzado
monthly_limit_exceeded	Límite mensual alcanzado
storage_limit_exceeded	Límite de almacenamiento alcanzado

Encabezados de Respuesta

Encabezado	Descripción
X-Request-Id	ID único de la solicitud
X-RateLimit-Limit	Límite de solicitudes por ventana
X-RateLimit-Remaining	Solicitudes restantes
X-RateLimit-Reset	Timestamp de reinicio del límite
Retry-After	Segundos a esperar (en 429)

Ejemplo de Manejo de Errores

async function handleApiResponse(response) {
  if (response.ok) {
    return response.json();
  }

  const error = await response.json();

  switch (response.status) {
    case 401:
      throw new Error('Autenticación fallida. Verifica tu clave API.');
    case 429:
      const retryAfter = response.headers.get('Retry-After');
      throw new Error(`Límite excedido. Intenta en ${retryAfter} segundos.`);
    case 500:
      throw new Error('Error del servidor. Intenta más tarde.');
    default:
      throw new Error(error.error?.message || 'Error desconocido');
  }
}

Próximos Pasos

• Soporte - Contacta a nuestro equipo para ayuda
• Autenticación - Volver a la guía de autenticación