Risoluzione dei problemi

La forma dell'errore corrisponde al protocollo chiamato. /v1/chat/completions e /v1/responses restituiscono errori in stile OpenAI; /v1/messages restituisce errori in stile Anthropic. I codici di stato HTTP sono identici in tutti e tre i protocolli.

Formato della risposta di errore

Formato OpenAI (/v1/chat/completions, /v1/responses)

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Formato Anthropic (/v1/messages)

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

401 · Autenticazione non riuscita authentication_error

{"error":{"message":"missing API key in Authorization header or X-API-Key","type":"authentication_error"}}

Cause

• Nessun header Authorization: Bearer (o X-API-Key) — messaggio: missing API key in Authorization header or X-API-Key.
• La chiave non corrisponde ad alcuna chiave attiva — messaggio: invalid API key.
• La chiave è scaduta — messaggio: API key expired.

Soluzione

1. Invia Authorization: Bearer sk-syn-… (o X-API-Key: sk-syn-…).
2. Verifica che la chiave sia attiva nella console e che sia stata copiata per intero.

400 · Richiesta non valida invalid_request

{"error":{"message":"model or models field is required","type":"invalid_request"}}

Cause

• Il campo model è mancante oppure il corpo JSON è vuoto o malformato.

Soluzione

1. Includi un model e un corpo JSON ben formato. Vedi il riferimento Chat Completions.

403 · Quota esaurita quota_exhausted

{"error":{"message":"API key quota exhausted","type":"quota_exhausted"}}

Cause

• Il saldo prepagato della chiave o dello spazio di lavoro è esaurito.

Soluzione

1. Ricarica il saldo dello spazio di lavoro. Nota: Synthorai restituisce 403 quota_exhausted per un saldo esaurito, non 429 — quindi il backoff esponenziale non aiuta; solo una ricarica lo risolve.

403 · Conformità — nessuna condivisione dei dati compliance_blocked / compliance_no_data_share

{"error":{"type":"compliance_blocked","code":"compliance_no_data_share","message":"model 'MODEL' is unavailable: your workspace compliance setting disallows providers that retain/train on data"}}

Cause

• Nel tuo spazio di lavoro è attivo no_provider_data_share e il modello richiesto è fornito solo da un provider che richiede conservazione/condivisione dei dati (ad es. un modello Bedrock o Vertex solo con condivisione dei dati).

Soluzione

1. Instrada la richiesta verso un modello senza conservazione, oppure disattiva l'interruttore di conformità dello spazio di lavoro se la condivisione dei dati è accettabile per quel carico. La classe di conservazione è un criterio di instradamento per modello — vedi l'analisi della conservazione a 30 giorni.

429 · Limite di velocità raggiunto rate_limit_exceeded

{"error":{"message":"rate limit exceeded: max 60 requests per minute","type":"rate_limit_exceeded"}}

Cause

• Hai superato il limite di richieste al minuto (RPM). Il messaggio indica il limite esatto.

Soluzione

1. Attendi e riprova con backoff esponenziale + jitter (snippet sotto). Richiedi un limite più alto se ti serve un throughput sostenuto.

502 · Nessun canale per il modello upstream_error

{"error":{"message":"no channels available for model \"MODEL\" in group \"default\"","type":"upstream_error"}}

Cause

• L'id del modello non corrisponde ad alcun canale instradabile per il tuo spazio di lavoro — un errore di battitura, un modello ritirato o uno non raggiungibile dal tuo piano.

Soluzione

1. Verifica l'id esatto nell'elenco dei modelli in tempo reale. Se un modello è stato ritirato di recente, scegline uno attuale.

BYOK: errori del provider upstream

Con bring-your-own-key, la richiesta viene eseguita sul tuo account del provider (AWS Bedrock, Google Vertex AI o l'API Anthropic), quindi Synthorai inoltra l'errore originale del provider senza modifiche — le risposte riportano usage.is_byok: true. La soluzione si trova nella console o nella configurazione di quel provider, non nel gateway. I più comuni sono le impostazioni di accesso ai modelli e di condivisione dei dati a livello di account:

Errori del provider upstream

Questi vengono inoltrati dal provider del modello con lo stato HTTP e il type del provider stesso. Solo 500 e 529 indicano il lato provider; trattali (e 429) come transitori e riprova, mentre i 4xx riflettono la richiesta. Riferimento completo: la documentazione degli errori di Anthropic.

Rate limit

I rate limit vengono applicati per chiave API per garantire un uso equo a tutti gli utenti.

Limiti predefiniti

Stai pianificando il throughput di token rispetto ai prezzi reali per token? Esegui il tuo carico di lavoro nel calcolatore dei costi API LLM.

Gestione degli errori 429

import time
import openai

client = openai.OpenAI(base_url="https://synthorai.io/v1", api_key="YOUR_API_KEY")

for attempt in range(5):
    try:
        response = client.chat.completions.create(
            model="gpt-5.4-mini",
            messages=[{"role": "user", "content": "Hello"}]
        )
        break
    except openai.RateLimitError as e:
        wait = 2 ** attempt  # exponential backoff
        print(f"Rate limited. Retrying in {wait}s...")
        time.sleep(wait)

async function withRetry(fn, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status === 429 && attempt < maxAttempts - 1) {
        const wait = Math.pow(2, attempt) * 1000;
        await new Promise(r => setTimeout(r, wait));
      } else throw err;
    }
  }
}

Ricevi un 502 o un sovraccarico su un modello? Scegli un'alternativa dalla comparazione dei prezzi dei modelli — ogni modello instradabile e il suo prezzo per token in un'unica tabella.