Skip to main content
POST
https://api.tracelm.ai
/
api
/
v1
/
tasks
/
{id}
/
fail
Fail Task
curl --request POST \
  --url https://api.tracelm.ai/api/v1/tasks/{id}/fail \
  --header 'Content-Type: application/json' \
  --data '
{
  "error": "<string>",
  "error_type": "<string>",
  "metadata": {}
}
'
{
  "status": "<string>",
  "failed_at": "<string>",
  "error": "<string>",
  "error_type": "<string>"
}
Marks a task as failed. Use this when your agent encounters an unrecoverable error.

​
Path Parameters

​
id
string
required
The task ID (UUID)

​
Request Body

​
error
string
required
Error message describing what went wrong
​
error_type
string
Error classification (e.g., timeout, api_error, validation_error)
​
metadata
object
Additional context about the failure

​
Response

​
status
string
Updated task status: failed
​
failed_at
string
Failure timestamp (ISO 8601)
​
error
string
The error message
​
error_type
string
The error classification

​
Example

curl -X POST "https://api.tracelm.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/fail" \
  -H "X-API-Key: $TRACELM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "error": "Payment gateway timeout after 3 retries",
    "error_type": "timeout",
    "metadata": {
      "retries": 3,
      "last_attempt": "2024-01-15T10:30:55Z"
    }
  }'

​
Response

{
  "status": "failed",
  "failed_at": "2024-01-15T10:31:00Z",
  "error": "Payment gateway timeout after 3 retries",
  "error_type": "timeout"
}
Once a task is marked as failed, it cannot be changed to completed. Create a new task if you need to retry the operation.