错误说明

本指南介绍在使用 Tripo API 时请求失败会发生什么，以及应如何处理。

错误响应

当请求不成功时，Tripo API 会返回包含错误码、错误描述和建议的错误响应。你可以利用这些信息定位问题并进行修复。大多数错误信息都具有可操作性，且遵循统一的 json 结构：

{
  "code": 1004,
  "message": "One or more of your parameter is invalid",
  "suggestion": "Refer to the API documentation for parameter requirements"
}

在任务查询过程中，任务也可能失败，此时同样会返回错误码用于说明原因：

{
  "code": 0,
  "data": {
    "task_id": "916ef2cf-02e5-4bed-97f3-d8a8196f7dfc",
    "type": "text_to_model",
    "status": "failed",
    "input": {
      "prompt": "A dachshund standing on a stool.",
      "model_version": "v2.5-20250123"
    },
    "output": {},
    "progress": 100,
    "create_time": 1768888519,
    "error_code": 1001,
    "prompt": "a dog",
    "queuing_num": -1,
    "running_left_time": -1,
    "result": {}
  }
}

关注响应头中的 Trace-Id

无论请求成功还是失败，响应头中都会包含名为 X-Tripo-Trace-ID 的 UUID 字段。

该 ID 会为每次请求随机生成，建议在日志中记录，便于追踪。

发生错误时，请在反馈问题时提供该 ID，便于我们更高效排查。

响应头示例如下：

HTTP/1.1 200 OK
Content-Type: application/json
X-Tripo-Trace-ID: 20516a36-f45c-4454-83c8-45877b75eac8
...

错误码列表

HTTP 状态码	Code	Message	Suggestion
500	1000	Unknown error on sever side	Please contact the support with request id
500	1001	Fatal error on server side	Please contact the support with request id
401	1002	Authentication failed	Check if your credentials is valid, and ensure you set it correctly
400	1003	The request body is malformed	Refer to the API documentation for request schema
400	1004	One or more of your parameter is invalid	Refer to the API documentation for parameter requirements
403	1005	You are not allowed to access this resource	Check if you have sufficent permission
429	1007	Rate limit exceeded, you've generated too many requests in a short amount of time	Please wait for a while and try again
429	2000	You have exceeded the limit of generation	Try again later. You can also check Retry-After header.
404	2001	The task is not found	Check if the task is committed by you or whether the format is correct
400	2002	This task type is not supported	Refer to API documentation for supported task types
400	2003	The image file is empty	Check if the file is corrupted
400	2004	This image file type is not supported	Refer to API documentation for supported image file types
400	2005	The draft task is not a success task	Retry with a success draft task
400	2006	The original task type is not supported	Retry with a task with supported task type
400	2007	The original task is not a succeeded task	Retry with a succeeded task
400	2008	The input is rejected due to violation of content policy	Please modify your input and retry
400	2009	The input prompt contains invalid characters	Please modify your input and retry
403	2010	You don't have enough credit to create this task	Please purchase more credit
400	2011	The input task type cannot be prerigcheck without model	Please provide a task with output containing a model
400	2012	The input task type is not valid	Please provide a rig task
403	2013	The priority is invalid	Contact the support if you need higher priority
400	2014	Error occurred when auditing	Please contact us for further suggestion
400	2015	The version has been deprecated, please try higher version	Try higher version please
400	2016	The request type has been deprecated	Try other available types please
400	2017	The version value is valid	Try correct version please
400	2018	The model is too complex to remesh	Please try another model
404	2019	The file is not found	Check uploading response to ensure if the file has uploaded successfully