Errori

UberLLM restituisce buste di errore in stile OpenAI così la gestione degli errori esistente funziona senza modifiche:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low to serve this request.",
    "type": "insufficient_credits"
  }
}

Superficie di inferenza (`/v1/*`)

HTTP	`code`	Significato	Cosa fare
402	`insufficient_credits`	Il tuo saldo prepagato non può coprire la prenotazione della richiesta.	Ricarica su Dashboard → Crediti.
402	`key_spend_cap_exceeded`	Questa chiave ha raggiunto il limite di spesa configurato (giornaliero / mensile / a vita).	Aumenta o rimuovi il limite della chiave, oppure usa un'altra chiave.
400	`invalid_request`	Il corpo della richiesta non è stato parsificato, o il modello ha rifiutato la richiesta (il messaggio ne indica il motivo).	Correggi la richiesta; non verrà ritentata.
413	`request_too_large`	Il corpo della richiesta supera i 10 MB (il più delle volte immagini inviate come base64).	Invia le immagini come link `https://`, o accorcia la conversazione. Non è stato addebitato nulla.
404	`model_not_found`	L'id `model` non è disponibile. Un prefisso `uberllm/` davanti va bene: `uberllm/deepseek/deepseek-v4.1-flash` raggiunge `deepseek/deepseek-v4.1-flash`.	Controlla `GET /v1/models`; correggi l'id.
400	`context_length_exceeded`	Il prompt è più lungo di quanto il modello accetti, chiunque lo venda. Su `/v1/chat/completions` senza una lista `models` risponde invece il modello più vicino che lo accetta (il `model` della risposta lo nomina); questo errore si verifica quando nessuno lo fa, o su `/v1/messages`. Il messaggio fornisce entrambe le dimensioni e nomina i modelli che lo accettano.	Invia meno, o scegli un modello nominato dal messaggio. Non è stato addebitato nulla.
400	`tools_not_supported`	La richiesta invia `tools` e il modello non può chiamarli, chiunque lo venda. Stessa regola di sostituzione di cui sopra. Il messaggio nomina i modelli che possono.	Invialo senza tools, o scegli un modello nominato dal messaggio. Non è stato addebitato nulla.
400	`max_price_exceeded`	Nessuno vende il modello all'interno del tuo `provider.max_price` in questo momento (e nessun modello in `models` potrebbe accettarlo).	Aumenta `max_price`, riprova più tardi, o nomina altri modelli. Non è stato addebitato nulla.
400	`unsupported_routing_option`	Un'opzione `provider` che UberLLM non può applicare (il messaggio la nomina).	Omettila; vedi Modelli e routing.
400	`invalid_metadata`	`metadata` non è un oggetto di fino a 16 valori di testo.	Correggi i tags; i numeri vanno tra virgolette.
400	`unknown_capability`	Un alias `best-price:` / `fastest:` non nomina alcun job.	Usa uno tra `chat`, `image`, `image-edit`, `text-to-video`, `image-to-video`, `music`, `speech`, `transcription`.
400	`wrong_endpoint`	Il modello (o alias) esegue un job che questa route non gestisce: un modello di immagine, video, musica, speech o transcription inviato a `/v1/chat/completions` o `/v1/messages`, un modello di chat inviato a una route multimediale, o speech e transcription scambiate. Il messaggio nomina la route corretta. Rifiutato prima che qualcosa venga eseguito; nulla viene addebitato, e Activity lo elenca come rifiutato.	Invialo alla route nominata dal messaggio (anche in `endpoints` su `/v1/models/{id}`).
503	`no_timing_data`	`fastest:` è stato richiesto prima che un numero sufficiente di richieste fosse cronometrato per confrontare i modelli.	Usa `best-price:` o nomina un modello.
429	`rate_limited`	Questa chiave ha superato il suo limite di richieste al minuto, o il marketplace ha continuato a rate-limiting dopo i tentativi automatici.	Riprova con un jitter; aumenta il rate limit della chiave.
503	`no_available_provider`	Nessuno può servire quel modello in questo momento, anche dopo i tentativi automatici (nessun venditore, ogni venditore fallisce o è troppo lento per iniziare, o le tue opzioni `provider` non hanno lasciato nulla a cui instradare), o un alias `best-price:` / `fastest:` non ha trovato alcun modello per il job disponibile in questo momento. Il messaggio nomina il modello o il job. Questo copre anche un venditore il cui account provider è fallito: UberLLM prova altri venditori e non trasmette mai l'errore di quel venditore come se la tua chiave fosse sbagliata.	Riprova a breve o scegli un altro modello. Non è stato addebitato nulla.
503	`service_unavailable`	Un problema temporaneo da parte di UberLLM.	Riprova tra qualche minuto.

Le richieste di immagini, video e musica aggiungono alcuni codici propri (image_required, invalid_image_url (un link a un'immagine sorgente che non porta a un'immagine), max_cost_too_low, idempotency_key_reused, artifact_expired); vedi Crea un video o un'immagine.

Una richiesta di chat rifiutata o fallita appare in Dashboard → Attività con il messaggio che ti è stato inviato. Le risposte di chat, immagine, video, musica, speech e transcription contengono un header X-Request-Id con lo stesso id della sua riga di Activity, errori inclusi.

I tentativi vengono eseguiti per te prima che venga restituito un errore: fino a 4 tentativi, solo prima del primo byte di contenuto. Vedi Modelli e routing.

Prenotazioni e interruzioni

UberLLM riserva un costo stimato prima del proxying e si regola in base all'utilizzo effettivo in seguito. Se una richiesta va in errore, viene interrotta, o ti disconnetti a metà streaming, la prenotazione non utilizzata viene rilasciata — ti viene addebitato solo il contenuto effettivamente prodotto. Gli streaming interrotti vengono riconciliati da una stima del tokenizer e segnalati in Dashboard → Attività.

Limitazione di frequenza

I limiti di frequenza per chiave sono applicati con una finestra fissa. Sulla superficie di inferenza, i controlli di limitazione di frequenza falliscono in modo chiuso — se UberLLM non può verificare il tuo limite, la richiesta viene rifiutata invece di essere servita senza contatore. Imposta (o aumenta) il limite di richieste per minuto di una chiave in Dashboard → API keys.

Ogni risposta autenticata /v1/* contiene la finestra corrente della chiave:

Intestazione	Significato
`X-RateLimit-Limit`	Richieste che questa chiave può inviare per minuto
`X-RateLimit-Remaining`	Richieste rimanenti nel minuto corrente
`X-RateLimit-Reset`	Quando la finestra si riavvia (secondi Unix)
`Retry-After`	In caso di `429` da questo limite: secondi da attendere prima di riprovare

Rallenta quando X-RateLimit-Remaining si avvicina a 0. Le intestazioni vengono omesse quando la finestra non può essere letta.

API del Venditore (`/api/v1/seller/*`)

Queste utilizzano codici REST standard:

HTTP	`code`	Significato
400	`invalid_request`	Validazione fallita (es. `endpoint_url` non-https, prezzi mancanti per `absolute`, `multiplier` fuori da `0 < m ≤ 1.5`). Il messaggio indica il campo.
400	`model_not_in_catalog`	`model_id` non è un modello di catalogo conosciuto.
401	`unauthorized`	JWT della dashboard mancante o non valido.
404	`seller_not_found`	Nessun venditore per la tua organizzazione — chiama `POST /api/v1/seller/register` prima.
404	`offer_not_found`	Nessuna offerta con quell'ID sotto il tuo venditore.
409	`invalid_status_transition`	Cambio di stato illegale — es. riprendere un'offerta `delisted` (rimossa è uno stato terminale).

Nota: una sonda di validazione fallita non è una risposta di errore. L'offerta viene creata/aggiornata con successo e restituita con status: "paused" e un last_probe_error che spiega il motivo — correggi l'endpoint e PATCH di nuovo a active per ri-sondare. Vedi Venditori.

Errori di autenticazione

HTTP	Significato
401	Header `Authorization` mancante/non valido. Le chiavi di inferenza sono `Bearer ull_...`; gli endpoint della dashboard utilizzano il JWT del tuo account.
403	La chiave è valida ma manca dello scope richiesto (ad esempio, una chiave di sola inferenza che chiama un endpoint della dashboard).