Error handling

H3 video task API · /api/v3

Error response

JSON · Parameter error example

{
  "error": {
    "code": "InvalidParameter",
    "message": "Check model, content and generation parameters",
    "request_id": "REQUEST_ID"
  }
}

Save the HTTP status,error.code, error.message and request ID. Gateway and middleware error codes may differ; do not rely only on example strings.

HTTP status codes

HTTP	Meaning	Recommended action
401	Authentication failed	Check the Bearer key.
402	Insufficient admission budget	Ask the administrator to adjust the request budget. This is not the amount already billed monthly.
403	Account / model access denied	Check account status and model permissions.
404	Task not found or expired	Check the account, ID and query protocol.
409	Idempotency / state conflict	Check whether the same key was used with a different request or the task can no longer be cancelled.
413	Input too large	Reduce image or request size.
422	Unsupported parameter or image	Check data types, image format and model specifications.
429	Rate limit / queue full	Follow Retry-After and keep the idempotency key.
500 / 502 / 503	Service error / capacity unavailable	Retry with backoff; keep the idempotency key for the same creation request.

Avoid duplicate generation

Network timeouts do not cancel server-side tasks. If you have an ID, keep querying it. If creation returned no ID, retry the same request with its original idempotency key.