Error Codes

When an error occurs, the Venice API returns an HTTP status code and a descriptive message. Some errors also include additional fields, such as refund status, suggested retry models, validation details, or request IDs.

Error response format

Most errors return an error field with a human-readable message:

{
  "error": "Invalid request parameters"
}

Some endpoints include additional fields that are specific to the endpoint. For example, video moderation errors can include whether credits were refunded:

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

Validation errors may include details and issues fields with field-level validation information:

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

Some OpenAI-compatible endpoints may return OpenAI-style error objects for specific cases, such as context length errors:

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

Missing credentials

A request with no credentials returns 402 Payment Required, not 401. Every paid route also accepts x402 wallet authentication, so the response is a payment challenge: it includes a PAYMENT-REQUIRED header and a body describing both ways to authenticate.

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

If you meant to use an API key, check that the Authorization: Bearer header is set. A key that is present but invalid returns 401.

Request format errors

These errors come from reading the request body, before any endpoint-specific validation runs.

HTTP Status	Message	Cause
400	`'Content-Type' must be 'application/json'`	A `POST`, `PUT`, or `PATCH` body sent without `Content-Type: application/json`. Endpoints that take file uploads also accept `multipart/form-data`
400	`Invalid JSON request`	The body is not valid JSON
400	`Invalid multipart request: malformed part header`	A `multipart/form-data` body that can’t be parsed
413	`Request body exceeds the maximum allowed size.`	The request body is too large
415	`Request encoding is not supported`	A `Content-Encoding` or charset the API can’t decode

A wrong Content-Type returns 400, not 415. Size-limit 413 responses also include a code field:

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

Error Code	HTTP Status	Message	Log Level
`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. Returned only by `/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.	-

Other errors

The table above is not exhaustive. Some errors are returned without a listed code, and messages can vary by model and endpoint, so branch on the HTTP status rather than on message text. Errors you may see that aren’t in the table:

HTTP Status	When it happens
400	An image input in a chat or Responses request is in an unsupported format
400	The requested voice isn’t available for the text-to-speech model
403	The request comes from an IP address that isn’t on the API key’s allowlist
403	The requested model isn’t permitted by the API key’s privacy setting
403	Access to the requested model is restricted. Contact [email protected]
409	A video, music, or voice-changer result is still uploading when you retrieve it. Retry shortly
410	The endpoint has been retired
422	Audio is too long or too short (voice cloning, voice changer, and audio jobs)
422	A video request’s input image has a width-to-height ratio outside the range the model accepts
422	A video request’s input was blocked by content moderation
500	Video or voice-changer generation failed
502	Speech synthesis failed upstream, or a generated video couldn’t be retrieved. Retry the request

​Error response format

​Missing credentials

​Request format errors

​Error codes

​Other errors

Error response format

Missing credentials

Request format errors

Error codes

Other errors