Retour à la documentation

Référence HTTP et Codes de Statut

Documentation complète des points d'accès, codes de statut et gestion des erreurs

par Arkangel AI Team•3 min de lecture

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