Errors

In this guide, we will talk about what happens when something fails in your work with Tripo API.

Error response

Whenever a request is unsuccessful, Tripo API will return an error response with an error code, description and suggestion. You can use this information to understand better what has gone wrong and how to fix it. Most of the error messages should be helpful and actionable, they also share a common json structure:

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

During your task query process, some tasks may fail. An error code will also be returned to make the reason clear:

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

Refer to Trace-Id in headers

All responses, whether successful or unsuccessful, include a standard header field named X-Tripo-Trace-ID in UUID.

This ID is randomly generated for each request. We recommend logging this value for tracking purposes.

In the event of an error, please provide this ID when reporting the issue to us for a more effective investigation.

Here is example response headers:

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

Error code list

HTTP status code	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