Maneja códigos públicos de error de Rivya API, estados HTTP, límites de tasa, conflictos de idempotencia y decisiones de reintento.

Rivya API devuelve códigos públicos de error estables en JSON. Trata el valor error.code como el contrato de integración.

Forma del error

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

Conserva requestId en tus logs cuando pidas a soporte de Rivya que investigue una solicitud de API fallida.

Códigos de error estables

Código	Estado HTTP	Significado	Acción sugerida
`public_api_disabled`	503	Las llamadas a la Public API están temporalmente desactivadas.	Reintenta más tarde o usa Studio manualmente.
`api_key_missing`	401	La solicitud no incluyó una clave API Bearer.	Envía `Authorization: Bearer rvya_sk_...`.
`api_key_invalid`	401	La clave no puede verificarse.	Revisa la clave y rótala si hace falta.
`api_key_revoked`	401	La clave fue revocada en Settings.	Crea una clave nueva.
`api_key_expired`	401	La clave ya no es válida.	Crea una clave nueva.
`api_scope_denied`	403	La clave no tiene el scope requerido.	Crea una clave con el scope necesario.
`rate_limited`	429	Demasiadas solicitudes en la ventana actual.	Retrocede y reintenta más tarde.
`validation_failed`	400	El body, el modelo, el prompt o los params no son válidos.	Compara tu body con la referencia del modelo.
`not_found`	404	La tarea solicitada no existe o no pertenece a la cuenta.	Revisa el ID público de tarea y el límite de cuenta.
`webhook_url_rejected`	400	La URL del endpoint de webhook no está permitida.	Usa una URL HTTPS pública sin credenciales, fragmentos, localhost ni direcciones de red privada.
`chat_model_not_supported`	400	El modelo seleccionado no está disponible para Chat API.	Lee `/api/v1/models` y elige un modelo de chat disponible.
`chat_session_conflict`	409	La sesión de chat no puede usarse para esta solicitud.	Usa una sesión creada por API que pertenezca a la misma cuenta y modelo.
`chat_attachment_not_supported`	400	El adjunto de chat no es compatible.	Sube una imagen mediante Files API y pasa su `file_id`.
`idempotency_conflict`	409	La misma clave de idempotencia se reutilizó con una entrada diferente.	Usa una clave nueva o reenvía exactamente el mismo body.
`insufficient_credits`	402	La cuenta no tiene créditos suficientes.	Añade créditos o elige una solicitud de menor costo.
`internal_error`	500	La solicitud no pudo completarse.	Reintenta con idempotencia o contacta con soporte usando `requestId`.

Límites de tasa

Rivya aplica límites de tasa de Public API a nivel de aplicación por clave API. El límite de producción por defecto se configura con PUBLIC_API_RATE_LIMIT_PER_MINUTE.

Cuando recibas rate_limited, usa backoff exponencial. No reintentes en un bucle cerrado.

Reintentos idempotentes

Envía Idempotency-Key con cada solicitud de producción POST /api/v1/generations y POST /api/v1/chat/completions.

Patrón recomendado:

genera una clave única por solicitud lógica de generación
reutiliza la misma clave solo al reintentar el mismo body
guarda el ID público de tarea devuelto junto con tu propio registro de trabajo
para Chat API, guarda el session_id devuelto cuando quieras continuar la misma conversación
no reutilices una clave para un modelo, prompt o params diferentes

Si la red falla después del envío, reintenta con el mismo body y el mismo Idempotency-Key. Rivya puede devolver la respuesta pública guardada en lugar de crear una tarea duplicada.

Decisiones de reintento

Reintenta estos con backoff:

public_api_disabled
rate_limited
internal_error
fallos temporales de red

No reintentes estos sin cambiar la entrada:

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

Errores y límites de la API

Forma del error

Códigos de error estables

Límites de tasa

Reintentos idempotentes

Decisiones de reintento

Páginas relacionadas

Tabla de contenido