Référence HTTP et Codes de Statut

Documentation complète de tous les points d'accès et codes de réponse de l'API.

URL de Base

https://api.arkangelai.com/v1

Points d'Accès Disponibles

Chat

Méthode	Point d'Accès	Description
POST	/chat	Envoyer un message et recevoir une réponse
POST	/chat/stream	Envoyer un message avec streaming de réponse

Conversations

Méthode	Point d'Accès	Description
GET	/conversations	Lister les conversations
GET	/conversations/:id	Obtenir une conversation
PATCH	/conversations/:id	Mettre à jour une conversation
DELETE	/conversations/:id	Supprimer une conversation
GET	/conversations/search	Rechercher dans les conversations
GET	/conversations/:id/export	Exporter une conversation

Fichiers

Méthode	Point d'Accès	Description
POST	/files	Télécharger un fichier
GET	/files	Lister les fichiers
GET	/files/:id	Obtenir les informations d'un fichier
DELETE	/files/:id	Supprimer un fichier

Utilisation

Méthode	Point d'Accès	Description
GET	/usage	Obtenir les métriques d'utilisation
GET	/usage/limits	Vérifier les limites
GET	/usage/endpoints	Utilisation par point d'accès
GET	/usage/errors	Historique des erreurs
GET	/usage/export	Exporter les données d'utilisation
POST	/usage/alerts	Configurer des alertes

Limites de Requêtes

Tous les points d'accès de l'API appliquent des limites de requêtes pour garantir une utilisation équitable et la stabilité de la plateforme. Les limites sont appliquées par utilisateur (identifié par votre clé API) à l'aide d'une fenêtre glissante.

Limites par Défaut

Point d'Accès	Limite	Fenêtre
POST /chat	20 requêtes	1 minute
POST /chat/stream	20 requêtes	1 minute
GET /conversations, GET /conversations/:id	60 requêtes	1 minute
PATCH /conversations/:id, DELETE /conversations/:id	30 requêtes	1 minute
POST /files	30 requêtes	1 minute
GET /files, GET /files/:id, DELETE /files/:id	60 requêtes	1 minute
GET /conversations/:id/export, GET /usage/export	5 requêtes	1 minute
GET /usage, GET /usage/*	60 requêtes	1 minute

Réponse de Limite de Requêtes

Lorsque vous dépassez une limite, l'API renvoie un statut 429 Too Many Requests avec les en-têtes suivants :

En-tête	Description
X-RateLimit-Limit	Nombre maximum de requêtes autorisées dans la fenêtre actuelle
X-RateLimit-Remaining	Requêtes restantes dans la fenêtre actuelle
X-RateLimit-Reset	Horodatage Unix de réinitialisation de la fenêtre
Retry-After	Secondes à attendre avant de réessayer

Attendez la durée spécifiée dans Retry-After avant d'envoyer une autre requête.

Codes de Statut HTTP

Réponses Réussies (2xx)

Code	Nom	Description
200	OK	Requête réussie
201	Created	Ressource créée avec succès
204	No Content	Requête réussie sans contenu de réponse

Erreurs Client (4xx)

Code	Nom	Description
400	Bad Request	Requête mal formée ou paramètres invalides
401	Unauthorized	Clé API manquante ou invalide
403	Forbidden	Pas de permission pour la ressource
404	Not Found	Ressource non trouvée
409	Conflict	Conflit avec l'état actuel
422	Unprocessable Entity	Données valides mais non traitables
429	Too Many Requests	Limite de requêtes dépassée

Erreurs Serveur (5xx)

Code	Nom	Description
500	Internal Server Error	Erreur interne du serveur
502	Bad Gateway	Erreur de passerelle
503	Service Unavailable	Service temporairement indisponible
504	Gateway Timeout	Délai d'attente dépassé

Format des Erreurs

Toutes les réponses d'erreur suivent ce format :

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "message": "La clé API fournie n'est pas valide",
    "param": "authorization",
    "request_id": "req_abc123"
  }
}

Champs de l'Erreur

Champ	Type	Description
type	string	Catégorie de l'erreur
code	string	Code spécifique de l'erreur
message	string	Description lisible de l'erreur
param	string	Paramètre qui a causé l'erreur (si applicable)
request_id	string	ID unique pour le suivi

Types d'Erreur

Type	Description
invalid_request_error	Paramètres invalides ou manquants
authentication_error	Problèmes d'authentification
permission_error	Permissions manquantes
not_found_error	La ressource n'existe pas
rate_limit_error	Limite de requêtes dépassée
api_error	Erreur interne de l'API

Codes d'Erreur Courants

Authentification

Code	Description
invalid_api_key	Clé API invalide
missing_api_key	Aucune clé API fournie
api_key_revoked	Clé API révoquée
api_key_expired	Clé API expirée

Requêtes

Code	Description
invalid_message	Message vide ou invalide
message_too_long	Message dépasse la limite de caractères
invalid_conversation_id	ID de conversation invalide
invalid_file_id	ID de fichier invalide

Fichiers

Code	Description
invalid_file_type	Type de fichier non supporté
file_too_large	Fichier dépasse la taille maximale
file_processing_failed	Erreur lors du traitement du fichier

Limites

Code	Description
rate_limit_exceeded	Limite de requêtes par seconde
daily_limit_exceeded	Limite quotidienne atteinte
monthly_limit_exceeded	Limite mensuelle atteinte
storage_limit_exceeded	Limite de stockage atteinte

En-têtes de Réponse

En-tête	Description
X-Request-Id	ID unique de la requête
X-RateLimit-Limit	Limite de requêtes par fenêtre
X-RateLimit-Remaining	Requêtes restantes
X-RateLimit-Reset	Timestamp de réinitialisation
Retry-After	Secondes à attendre (sur 429)

Exemple de Gestion des Erreurs

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

  const error = await response.json();

  switch (response.status) {
    case 401:
      throw new Error('Authentification échouée. Vérifiez votre clé API.');
    case 429:
      const retryAfter = response.headers.get('Retry-After');
      throw new Error(`Limite dépassée. Réessayez dans ${retryAfter} secondes.`);
    case 500:
      throw new Error('Erreur serveur. Réessayez plus tard.');
    default:
      throw new Error(error.error?.message || 'Erreur inconnue');
  }
}

Prochaines Étapes

• Support - Contactez notre équipe pour obtenir de l'aide
• Authentification - Retour au guide d'authentification