Códigos de erro

Quando ocorre um erro, a API Venice retorna um código de status HTTP e uma mensagem descritiva. Alguns erros também incluem campos adicionais, como status de reembolso, modelos sugeridos para nova tentativa, detalhes de validação ou IDs de requisição.

Formato da resposta de erro

A maioria dos erros retorna um campo error com uma mensagem legível por humanos:

{
  "error": "Invalid request parameters"
}

Alguns endpoints incluem campos adicionais específicos do endpoint. Por exemplo, erros de moderação de vídeo podem incluir se os créditos foram reembolsados:

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

Erros de validação podem incluir campos details e issues com informações de validação por campo:

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

Alguns endpoints compatíveis com OpenAI podem retornar objetos de erro no estilo OpenAI para casos específicos, como erros de comprimento 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"
  }
}

Credenciais ausentes

Uma solicitação sem credenciais retorna 402 Payment Required, e não 401. Todas as rotas pagas também aceitam autenticação por carteira x402, então a resposta é um desafio de pagamento: ela inclui um cabeçalho PAYMENT-REQUIRED e um corpo descrevendo as duas formas de autenticação.

{
  "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 você pretendia usar uma chave de API, verifique se o cabeçalho Authorization: Bearer está definido. Uma chave presente, mas inválida, retorna 401.

Erros de formato da requisição

Esses erros ocorrem durante a leitura do corpo da requisição, antes de qualquer validação específica do endpoint.

Status HTTP	Mensagem	Causa
400	`'Content-Type' must be 'application/json'`	Um corpo de `POST`, `PUT` ou `PATCH` enviado sem `Content-Type: application/json`. Endpoints que recebem upload de arquivos também aceitam `multipart/form-data`
400	`Invalid JSON request`	O corpo não é um JSON válido
400	`Invalid multipart request: malformed part header`	Um corpo `multipart/form-data` que não pode ser interpretado
413	`Request body exceeds the maximum allowed size.`	O corpo da requisição é grande demais
415	`Request encoding is not supported`	Um `Content-Encoding` ou charset que a API não consegue decodificar

Um Content-Type incorreto retorna 400, não 415. Respostas 413 por limite de tamanho também incluem um campo code:

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

Código de erro	Status HTTP	Mensagem	Nível 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. Retornado apenas por `/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.	-

Outros erros

A tabela acima não é exaustiva. Alguns erros são retornados sem um código listado, e as mensagens podem variar conforme o modelo e o endpoint, então baseie sua lógica no status HTTP e não no texto da mensagem. Erros que você pode encontrar e que não estão na tabela:

Status HTTP	Quando ocorre
400	Uma imagem de entrada em uma requisição de chat ou Responses está em um formato não suportado
400	A voz solicitada não está disponível para o modelo de text-to-speech
403	A requisição vem de um endereço IP que não está na allowlist da chave de API
403	O modelo solicitado não é permitido pela configuração de privacidade da chave de API
403	O acesso ao modelo solicitado é restrito. Entre em contato com [email protected]
409	Um resultado de vídeo, música ou voice changer ainda está sendo enviado quando você tenta recuperá-lo. Tente novamente em instantes
410	O endpoint foi descontinuado
422	O áudio é longo ou curto demais (clonagem de voz, voice changer e jobs de áudio)
422	A imagem de entrada de uma requisição de vídeo tem uma proporção entre largura e altura fora do intervalo aceito pelo modelo
422	A entrada de uma requisição de vídeo foi bloqueada pela moderação de conteúdo
500	A geração de vídeo ou de voice changer falhou
502	A síntese de fala falhou no provedor upstream, ou um vídeo gerado não pôde ser recuperado. Tente a requisição novamente

​Formato da resposta de erro

​Credenciais ausentes

​Erros de formato da requisição

​Códigos de erro

​Outros erros

Formato da resposta de erro

Credenciais ausentes

Erros de formato da requisição

Códigos de erro

Outros erros