Codici di errore - Runbase Docs

Gli errori API noti restituiscono un corpo JSON con questa struttura:

{
  "error": {
    "message": "Human-readable description",
    "code": "error_code"
  }
}

Riferimento errori

400 Bad Request

Code	Cause	Fix
`invalid_json`	Il corpo della richiesta non è JSON valido	Controlla la sintassi del tuo JSON
`missing_model`	Il campo `model` è mancante o non è una stringa	Includi `"model": "provider/name"` nel corpo della richiesta
`missing_input`	Il campo `input` è mancante o non è un oggetto	Includi `"input": {...}` nel corpo della richiesta
`invalid_input`	L'input non corrisponde allo schema del modello	Controlla il riferimento API del modello per i campi richiesti e i valori validi
`model_not_found`	L'ID del modello non corrisponde ad alcun modello disponibile	Consulta la pagina dei modelli per gli ID modello validi

401 Unauthorized

Code	Cause	Fix
`missing_api_key`	Nessun header `Authorization` o formato errato	Includi `Authorization: Bearer sk-...` nella tua richiesta
`invalid_api_key`	La chiave non è valida, è disabilitata o è scaduta	Crea una nuova chiave o riabilita quella esistente in Impostazioni → API Keys

402 Payment Required

Code	Cause	Fix
`insufficient_balance`	Il tuo balance è troppo basso per questa esecuzione	Ricarica il tuo balance in Impostazioni → Credits

403 Forbidden

Code	Cause	Fix
`api_key_spend_limit_exceeded`	È stato raggiunto il limite di spesa a vita della chiave	Aumenta il limite di spesa in Impostazioni → API Keys
`ip_not_allowed`	Il tuo IP non è nella whitelist della chiave	Aggiungi il tuo IP all'elenco consentito della chiave, oppure rimuovi la whitelist

429 Too Many Requests

Code	Cause	Fix
`RATE_LIMITED`	Troppe richieste in una breve finestra temporale	Attendi e riprova. Consulta i limiti di frequenza
`USAGE_EXCEEDED`	La quota di utilizzo della chiave è esaurita	Contatta il supporto o crea una nuova chiave

404 Not Found

Code	Cause	Fix
`run_not_found`	Nessuna run con questo ID per il tuo account	Verifica che l'ID della run sia corretto e sia stato creato con questa API key

500 Internal Server Error

Un errore imprevisto dalla nostra parte. Se il problema persiste, contatta support@runbase.net.

Gestione degli errori nel codice

response=$(curl -s -w "\n%{http_code}" https://runbase.net/api/v1/runs \
  -H "Authorization: Bearer $RUNBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "google/nano-banana-2", "input": {"prompt": "test"}}')
 
http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | head -1)
 
if [ "$http_code" -ne 201 ]; then
  echo "Error $http_code: $(echo $body | jq -r '.error.message')"
fi

Per gli errori 429, implementa un backoff esponenziale — attendi 1s, poi 2s, poi 4s prima di riprovare.