Gérez les codes d'erreur publics de l'API Rivya, les statuts HTTP, les limites de débit, les conflits d'idempotence et les décisions de nouvelle tentative.

L'API Rivya renvoie des codes d'erreur publics stables en JSON. Traitez la valeur error.code comme le contrat d'intégration.

Format des erreurs

{
  "error": {
    "code": "api_key_missing",
    "message": "A valid Bearer API key is required.",
    "requestId": "req_..."
  }
}

Conservez requestId dans vos logs lorsque vous demandez au support Rivya d'enquêter sur une requête API échouée.

Codes d'erreur stables

Code	Statut HTTP	Signification	Action suggérée
`public_api_disabled`	503	Les appels à l'API publique sont temporairement désactivés.	Réessayez plus tard ou utilisez le Studio manuellement.
`api_key_missing`	401	La requête n'inclut pas de clé API Bearer.	Envoyez `Authorization: Bearer rvya_sk_...`.
`api_key_invalid`	401	La clé ne peut pas être vérifiée.	Vérifiez la clé et effectuez une rotation si nécessaire.
`api_key_revoked`	401	La clé a été révoquée dans les paramètres.	Créez une nouvelle clé.
`api_key_expired`	401	La clé n'est plus valide.	Créez une nouvelle clé.
`api_scope_denied`	403	La clé n'a pas le scope requis.	Créez une clé avec le scope nécessaire.
`rate_limited`	429	Trop de requêtes dans la fenêtre actuelle.	Ralentissez et réessayez plus tard.
`validation_failed`	400	Le body, le modèle, le prompt ou les paramètres sont invalides.	Comparez votre body avec la référence du modèle.
`not_found`	404	La tâche demandée n'existe pas ou n'appartient pas au compte.	Vérifiez l'ID de tâche public et la limite de compte.
`webhook_url_rejected`	400	L'URL de l'endpoint webhook n'est pas autorisée.	Utilisez une URL publique HTTPS sans identifiants, fragments, localhost ni adresses de réseau privé.
`chat_model_not_supported`	400	Le modèle sélectionné n'est pas disponible pour l'API Chat.	Lisez `/api/v1/models` et choisissez un modèle de chat disponible.
`chat_session_conflict`	409	La session de chat ne peut pas être utilisée pour cette requête.	Utilisez une session créée par l'API, appartenant au même compte et au même modèle.
`chat_attachment_not_supported`	400	La pièce jointe de chat n'est pas prise en charge.	Importez une image via l'API Files et transmettez son `file_id`.
`idempotency_conflict`	409	La même clé d'idempotence a été réutilisée avec une entrée différente.	Utilisez une nouvelle clé ou renvoyez exactement le même body.
`insufficient_credits`	402	Le compte n'a pas assez de crédits.	Ajoutez des crédits ou choisissez une requête moins coûteuse.
`internal_error`	500	La requête n'a pas pu être terminée.	Réessayez avec l'idempotence ou contactez le support avec `requestId`.

Limites de débit

Rivya applique des limites de débit d'API publique au niveau applicatif par clé API. La limite de production par défaut est configurée par PUBLIC_API_RATE_LIMIT_PER_MINUTE.

Lorsque vous recevez rate_limited, utilisez un backoff exponentiel. Ne relancez pas en boucle serrée.

Nouvelles tentatives idempotentes

Envoyez Idempotency-Key avec chaque requête de production POST /api/v1/generations et POST /api/v1/chat/completions.

Modèle recommandé :

générez une clé unique par requête de génération logique
réutilisez la même clé uniquement lorsque vous réessayez le même body
stockez l'ID de tâche public renvoyé avec votre propre enregistrement de job
pour l'API Chat, stockez le session_id renvoyé lorsque vous voulez continuer la même conversation
ne réutilisez pas une clé pour un autre modèle, prompt ou ensemble de paramètres

Si le réseau échoue après la soumission, réessayez avec le même body et la même Idempotency-Key. Rivya peut renvoyer la réponse publique stockée au lieu de créer une tâche en double.

Décisions de nouvelle tentative

Réessayez ceux-ci avec backoff :

public_api_disabled
rate_limited
internal_error
échecs réseau temporaires

Ne réessayez pas ceux-ci sans changer l'entrée :

api_key_invalid
api_key_revoked
api_scope_denied
validation_failed
webhook_url_rejected
chat_model_not_supported
chat_session_conflict
chat_attachment_not_supported
idempotency_conflict
insufficient_credits

Erreurs et limites API

Format des erreurs

Codes d'erreur stables

Limites de débit

Nouvelles tentatives idempotentes

Décisions de nouvelle tentative

Pages associées

Table des matières