Gestisci codici di errore pubblici Rivya API, valori di stato HTTP, rate limit, conflitti di idempotenza e decisioni di retry.

Rivya API restituisce codici di errore pubblici stabili in JSON. Considera il valore error.code come contratto di integrazione.

Forma dell'errore

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

Conserva requestId nei tuoi log quando chiedi al supporto Rivya di indagare su una richiesta API fallita.

Codici di errore stabili

Code	Stato HTTP	Significato	Azione suggerita
`public_api_disabled`	503	Le chiamate Public API sono temporaneamente disabilitate.	Riprova più tardi o usa Studio manualmente.
`api_key_missing`	401	La richiesta non includeva una chiave API Bearer.	Invia `Authorization: Bearer rvya_sk_...`.
`api_key_invalid`	401	La chiave non può essere verificata.	Controlla la chiave e ruotala se necessario.
`api_key_revoked`	401	La chiave è stata revocata in Settings.	Crea una nuova chiave.
`api_key_expired`	401	La chiave non è più valida.	Crea una nuova chiave.
`api_scope_denied`	403	La chiave non ha lo scope richiesto.	Crea una chiave con lo scope necessario.
`rate_limited`	429	Troppe richieste nella finestra attuale.	Riduci il ritmo e riprova più tardi.
`validation_failed`	400	Body, modello, prompt o parametri non sono validi.	Confronta il body con il riferimento del modello.
`not_found`	404	Il task richiesto non esiste o non appartiene all'account.	Controlla l'ID pubblico del task e il perimetro dell'account.
`webhook_url_rejected`	400	L'URL dell'endpoint webhook non è consentito.	Usa un URL HTTPS pubblico senza credenziali, frammenti, localhost o indirizzi di rete privata.
`chat_model_not_supported`	400	Il modello selezionato non è disponibile per Chat API.	Leggi `/api/v1/models` e scegli un modello chat disponibile.
`chat_session_conflict`	409	La sessione chat non può essere usata per questa richiesta.	Usa una sessione creata via API, appartenente allo stesso account e modello.
`chat_attachment_not_supported`	400	L'allegato chat non è supportato.	Carica un'immagine tramite Files API e passa il suo `file_id`.
`idempotency_conflict`	409	La stessa chiave di idempotenza è stata riutilizzata con input diverso.	Usa una nuova chiave o invia di nuovo esattamente lo stesso body.
`insufficient_credits`	402	L'account non ha crediti sufficienti.	Aggiungi crediti o scegli una richiesta a costo inferiore.
`internal_error`	500	La richiesta non ha potuto essere completata.	Riprova con idempotenza o contatta il supporto con `requestId`.

Rate limit

Rivya applica rate limit Public API a livello applicativo per ogni chiave API. Il limite di produzione predefinito è configurato da PUBLIC_API_RATE_LIMIT_PER_MINUTE.

Quando ricevi rate_limited, usa backoff esponenziale. Non riprovare in un ciclo serrato.

Retry idempotenti

Invia Idempotency-Key con ogni richiesta di produzione POST /api/v1/generations e POST /api/v1/chat/completions.

Pattern consigliato:

genera una chiave unica per ogni richiesta logica di generazione
riusa la stessa chiave solo quando ritenti lo stesso body
salva l'ID pubblico del task restituito nel tuo record job
per Chat API, salva il session_id restituito quando vuoi continuare la stessa conversazione
non riutilizzare una chiave per modello, prompt o parametri diversi

Se la rete fallisce dopo l'invio, riprova con lo stesso body e la stessa Idempotency-Key. Rivya può restituire la risposta pubblica salvata invece di creare un task duplicato.

Decisioni di retry

Riprova questi errori con backoff:

public_api_disabled
rate_limited
internal_error
errori di rete temporanei

Non riprovare questi errori senza cambiare input:

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

Errori e limiti API

Forma dell'errore

Codici di errore stabili

Rate limit

Retry idempotenti

Decisioni di retry

Pagine correlate

Indice