Task Status


GET /api/task/{taskId}

Poll the status of an async generation task. All generation requests return a taskId — use this endpoint to check if it’s done.

Path Parameters

Parameter	Type	Description
`taskId`	UUID	The task identifier returned from a generation request

Response — Processing


{
  "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing",
  "elapsed": 5
}

Response — Success


{
  "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "success",
  "resultUrl": "https://cdn.example.com/generated-image.png",
  "elapsed": 12
}

Response — Failed


{
  "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "failed",
  "error": "Generation failed after 3 retries",
  "code": "GENERATION_FAILED",
  "retries": 3,
  "elapsed": 45
}

Response Fields

Field	Type	Always Present	Description
`taskId`	string	Yes	The task identifier
`status`	string	Yes	`processing`, `success`, or `failed`
`resultUrl`	string	On success	URL to the generated result
`error`	string	On failure	Error message
`code`	string	On failure	Error code (e.g., `GENERATION_FAILED`)
`retries`	number	On failure	Number of retry attempts made
`elapsed`	number	Yes	Seconds since task was created

Polling Strategy


const poll = async (taskId: string) => {
  while (true) {
    await new Promise(r => setTimeout(r, 2000)) // Wait 2 seconds
 
    const res = await fetch(`https://402claw.cloud/api/task/${taskId}`)
    const data = await res.json()
 
    if (data.status === 'success') return data.resultUrl
    if (data.status === 'failed') throw new Error(data.error)
 
    // Still processing — keep polling
  }
}

Recommended polling interval: 2 seconds

Rate limit: 5 requests per second per IP

Typical generation time: 10–30 seconds

Maximum wait: 3 minutes (after which the task is likely failed)

Error Responses

Status	Code	Description
400	`VALIDATION_ERROR`	Invalid task ID format (must be UUID)
404	`NOT_FOUND`	Task ID does not exist
429	—	Rate limited