Codici di errore

Quando si verifica un errore, l’API Venice restituisce un codice di stato HTTP e un messaggio descrittivo. Alcuni errori includono anche campi aggiuntivi, come lo stato del rimborso, modelli di retry suggeriti, dettagli di validazione o ID di richiesta.

Formato della risposta di errore

La maggior parte degli errori restituisce un campo error con un messaggio leggibile:

{
  "error": "Invalid request parameters"
}

Alcuni endpoint includono campi aggiuntivi specifici dell’endpoint. Ad esempio, gli errori di moderazione video possono indicare se i crediti sono stati rimborsati:

{
  "error": "Your generation was blocked due to the model provider's content policies. Credits have been refunded.",
  "credits_refunded": true
}

Gli errori di validazione possono includere i campi details e issues con informazioni di validazione a livello di campo:

{
  "error": "Invalid request parameters",
  "details": {
    "_errors": [],
    "field": {
      "_errors": ["Field is required"]
    }
  },
  "issues": []
}

Alcuni endpoint compatibili con OpenAI possono restituire oggetti di errore in stile OpenAI per casi specifici, come gli errori di lunghezza del contesto:

{
  "error": {
    "message": "Your request exceeds the model's maximum context. Please reduce your prompt or completion length.",
    "type": "invalid_request_error",
    "param": "messages",
    "code": "context_length_exceeded"
  }
}

Credenziali mancanti

Una richiesta senza credenziali restituisce 402 Payment Required, non 401. Ogni route a pagamento accetta anche l’autenticazione tramite wallet x402, quindi la risposta è una richiesta di pagamento: include un header PAYMENT-REQUIRED e un body che descrive entrambi i modi per autenticarsi.

{
  "x402Version": 2,
  "error": "Authentication required",
  "accepts": [ ... ],
  "authOptions": {
    "apiKey": {
      "header": "Authorization: Bearer YOUR_API_KEY",
      "getKey": "https://venice.ai/settings/api"
    },
    "x402Wallet": {
      "header": "SIGN-IN-WITH-X",
      "topUp": "POST /api/v1/x402/top-up"
    }
  }
}

Se intendevi usare una chiave API, verifica che l’header Authorization: Bearer sia impostato. Una chiave presente ma non valida restituisce 401.

Errori di formato della richiesta

Questi errori derivano dalla lettura del body della richiesta, prima che venga eseguita qualsiasi validazione specifica dell’endpoint.

Stato HTTP	Messaggio	Causa
400	`'Content-Type' must be 'application/json'`	Un body `POST`, `PUT` o `PATCH` inviato senza `Content-Type: application/json`. Gli endpoint che accettano upload di file accettano anche `multipart/form-data`
400	`Invalid JSON request`	Il body non è un JSON valido
400	`Invalid multipart request: malformed part header`	Un body `multipart/form-data` che non può essere analizzato
413	`Request body exceeds the maximum allowed size.`	Il body della richiesta è troppo grande
415	`Request encoding is not supported`	Un `Content-Encoding` o un charset che l’API non riesce a decodificare

Un Content-Type errato restituisce 400, non 415. Le risposte 413 per il limite di dimensione includono anche un campo code:

{
  "code": "PAYLOAD_TOO_LARGE",
  "error": "Request body exceeds the maximum allowed size."
}

Codice di errore	Stato HTTP	Messaggio	Livello di log
`AUTHENTICATION_FAILED`	401	Authentication failed	-
`AUTHENTICATION_FAILED_INACTIVE_KEY`	401	Authentication failed - Pro subscription is inactive. Please upgrade your subscription to continue using the API	-
`X402_INVALID_SIGN_IN`	401	Invalid Sign-in-with-x signature	-
`PRO_ONLY_MODEL`	401	This model is only available to Pro users	-
`INSUFFICIENT_BALANCE`	402	Insufficient USD or Diem balance to complete request. Visit https://venice.ai/settings/api to add credits.	-
`API_KEY_DIEM_SPEND_LIMIT_EXCEEDED`	402	API key DIEM spend limit exceeded. Your account may still have DIEM balance, but this API key has reached its configured DIEM spending limit.	-
`API_KEY_USD_SPEND_LIMIT_EXCEEDED`	402	API key USD spend limit exceeded. Your account may still have USD balance, but this API key has reached its configured USD spending limit.	-
`UNAUTHORIZED`	403	Unauthorized access	-
`API_ACCESS_DISABLED`	403	API access has been disabled for this account. Please contact [email protected]	-
`X402_WALLET_MISMATCH`	403	You can only access resources for your own wallet	-
`INVALID_REQUEST`	400	Invalid request parameters	-
`INVALID_MODEL`	400	Invalid model specified	-
`REQUEST_ID_NOT_FOUND`	400	Request ID is invalid.	-
`INVALID_AUDIO_FORMAT`	400	Invalid audio format. Supported formats are WAV and MP3.	-
`INVALID_VIDEO_FORMAT`	400	Invalid video format. Supported formats include MP4, MOV, WebM, MKV, AVI, and others.	-
`CORRUPTED_IMAGE`	400	The image file is corrupted or unreadable	-
`IMAGE_TOO_SMALL`	400	Image dimensions are too small	-
`TOO_MANY_TOKENS`	400	Your request exceeds the model’s maximum context. Please reduce your prompt or completion length.	-
`CHARACTER_NOT_FOUND`	404	No character could be found from the provided character_slug	-
`MODEL_NOT_FOUND`	404	Specified model not found	-
`MEDIA_NOT_FOUND`	404	Media could not be found. Request may be invalid, expired, or deleted.	-
`PAYLOAD_TOO_LARGE`	413	The request payload is too large. Please reduce the size of your request.	-
`INVALID_CONTENT_TYPE`	415	Invalid request content-type. Restituito solo da `/image/multi-edit`	-
`VIDEO_DURATION_TOO_LONG`	422	Video duration exceeds the maximum allowed.	-
`VIDEO_DURATION_TOO_SHORT`	422	Video duration is too short.	-
`IMAGE_TOO_LARGE`	422	Image dimensions exceed the maximum allowed.	-
`CONTENT_POLICY_VIOLATION`	422	Your prompt violates the content policy of Venice.ai or the model provider	-
`ASR_UPSTREAM_VALIDATION_FAILED`	422	The audio could not be processed for transcription. Common causes: zero-length, silent, corrupt, or unsupported-language audio. Please verify the file and retry.	warn
`RATE_LIMIT_EXCEEDED`	429	Rate limit exceeded	-
`MODEL_OVERLOADED`	429	The model is currently overloaded. Please try again later.	-
`INFERENCE_FAILED`	500	Inference processing failed	error
`UPSCALE_FAILED`	500	Image upscaling failed	error
`IMAGE_EDIT_ERROR`	500	Image edit failed	error
`UNKNOWN_ERROR`	500	An unknown error occurred	error
`TEE_ATTESTATION_FAILED`	502	TEE attestation request failed. The Trusted Execution Environment provider may be temporarily unavailable.	error
`TEE_SIGNATURE_FAILED`	502	TEE signature request failed. The Trusted Execution Environment provider may be temporarily unavailable.	error
`ASR_UPSTREAM_FAILED`	502	Audio transcription failed due to a temporary upstream error. Please retry.	warn
`MODEL_OFFLINE`	503	The model is temporarily offline. Please try again later.	-
`MODEL_AT_CAPACITY`	503	The model is at capacity. Please try again later.	-
`REQUEST_TIMEOUT`	504	The request took too long to complete and was timed-out. For non-streaming requests, use the streaming API by setting `stream=true`. A streaming chat completion that times out before the model’s first chunk reports the failure as an in-band SSE error frame instead.	-

Altri errori

La tabella precedente non è esaustiva. Alcuni errori vengono restituiti senza un codice elencato e i messaggi possono variare in base al modello e all’endpoint, quindi basa la logica sullo stato HTTP anziché sul testo del messaggio. Errori che potresti incontrare e che non sono nella tabella:

Stato HTTP	Quando si verifica
400	Un’immagine in input in una richiesta chat o Responses è in un formato non supportato
400	La voce richiesta non è disponibile per il modello text-to-speech
403	La richiesta proviene da un indirizzo IP che non è nella allowlist della chiave API
403	Il modello richiesto non è consentito dall’impostazione di privacy della chiave API
403	L’accesso al modello richiesto è limitato. Contatta [email protected]
409	Un risultato video, musicale o di voice changer è ancora in fase di upload quando lo recuperi. Riprova a breve
410	L’endpoint è stato dismesso
422	L’audio è troppo lungo o troppo corto (voice cloning, voice changer e job audio)
422	L’immagine in input di una richiesta video ha un rapporto larghezza/altezza al di fuori dell’intervallo accettato dal modello
422	L’input di una richiesta video è stato bloccato dalla moderazione dei contenuti
500	La generazione video o di voice changer non è riuscita
502	La sintesi vocale non è riuscita a monte, oppure non è stato possibile recuperare un video generato. Riprova la richiesta

​Formato della risposta di errore

​Credenziali mancanti

​Errori di formato della richiesta

​Codici di errore

​Altri errori

Formato della risposta di errore

Credenziali mancanti

Errori di formato della richiesta

Codici di errore

Altri errori