Códigos de error

Cuando ocurre un error, la API de Venice devuelve un código de estado HTTP y un mensaje descriptivo. Algunos errores también incluyen campos adicionales, como estado de reembolso, modelos sugeridos para reintentar, detalles de validación o IDs de solicitud.

Formato de respuesta de error

La mayoría de los errores devuelven un campo error con un mensaje legible para humanos:

{
  "error": "Invalid request parameters"
}

Algunos endpoints incluyen campos adicionales específicos del endpoint. Por ejemplo, los errores de moderación de vídeo pueden incluir si se reembolsaron los créditos:

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

Los errores de validación pueden incluir campos details e issues con información de validación a nivel de campo:

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

Algunos endpoints compatibles con OpenAI pueden devolver objetos de error al estilo de OpenAI para casos específicos, como errores de longitud de contexto:

{
  "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"
  }
}

Credenciales ausentes

Una solicitud sin credenciales devuelve 402 Payment Required, no 401. Todas las rutas de pago también aceptan autenticación con billetera x402, por lo que la respuesta es un desafío de pago: incluye un encabezado PAYMENT-REQUIRED y un cuerpo que describe ambas formas de autenticarse.

{
  "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"
    }
  }
}

Si querías usar una clave de API, comprueba que el encabezado Authorization: Bearer esté configurado. Una clave presente pero no válida devuelve 401.

Errores de formato de la solicitud

Estos errores se producen al leer el cuerpo de la solicitud, antes de que se ejecute cualquier validación específica del endpoint.

Estado HTTP	Mensaje	Causa
400	`'Content-Type' must be 'application/json'`	Un cuerpo `POST`, `PUT` o `PATCH` enviado sin `Content-Type: application/json`. Los endpoints que aceptan subida de archivos también aceptan `multipart/form-data`
400	`Invalid JSON request`	El cuerpo no es JSON válido
400	`Invalid multipart request: malformed part header`	Un cuerpo `multipart/form-data` que no se puede analizar
413	`Request body exceeds the maximum allowed size.`	El cuerpo de la solicitud es demasiado grande
415	`Request encoding is not supported`	Un `Content-Encoding` o charset que la API no puede decodificar

Un Content-Type incorrecto devuelve 400, no 415. Las respuestas 413 por límite de tamaño también incluyen un campo code:

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

Código de error	Estado HTTP	Mensaje	Nivel de 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. Solo lo devuelve `/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.	-

Otros errores

La tabla anterior no es exhaustiva. Algunos errores se devuelven sin un código de la lista, y los mensajes pueden variar según el modelo y el endpoint, así que basa tu lógica en el estado HTTP y no en el texto del mensaje. Errores que puedes encontrar y que no están en la tabla:

Estado HTTP	Cuándo ocurre
400	Una imagen de entrada en una solicitud de chat o de Responses está en un formato no compatible
400	La voz solicitada no está disponible para el modelo de texto a voz
403	La solicitud procede de una dirección IP que no está en la lista de permitidas de la clave de API
403	La configuración de privacidad de la clave de API no permite el modelo solicitado
403	El acceso al modelo solicitado está restringido. Contacta con [email protected]
409	Un resultado de vídeo, música o cambio de voz aún se está subiendo cuando lo recuperas. Reinténtalo en breve
410	El endpoint se ha retirado
422	El audio es demasiado largo o demasiado corto (clonación de voz, cambio de voz y trabajos de audio)
422	La imagen de entrada de una solicitud de vídeo tiene una relación entre ancho y alto fuera del rango que acepta el modelo
422	La entrada de una solicitud de vídeo fue bloqueada por la moderación de contenido
500	Falló la generación de vídeo o de cambio de voz
502	La síntesis de voz falló en el proveedor, o no se pudo recuperar un vídeo generado. Reintenta la solicitud

​Formato de respuesta de error

​Credenciales ausentes

​Errores de formato de la solicitud