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