Error Codes
All API errors return a JSON response with an error field and optional details.
{
"error": "Human-readable error message",
"details": [{ "field": "title", "message": "Required field is missing" }]
}
The details array is included for validation errors (400) and contains field-level error information.
HTTP Status Codes
| Code | Meaning | When |
|---|
200 | OK | Successful read or update |
201 | Created | Resource successfully created |
400 | Bad Request | Invalid JSON, missing required fields, validation errors |
401 | Unauthorized | Missing Authorization header, invalid or expired token |
403 | Forbidden | Token lacks the required scope for this operation |
404 | Not Found | Resource doesn't exist or belongs to a different organization |
409 | Conflict | Operation conflicts with current state (e.g., cancelling a non-pending task) |
500 | Internal Server Error | Unexpected server error |
Common Errors
Authentication Errors
| Error | Cause | Solution |
|---|
| "Unauthorized" | No Authorization header | Add Authorization: Bearer htk_... header |
| "Invalid token" | Token is malformed | Check token format (should start with htk_) |
| "Token revoked" | Token was revoked | Create a new token in Settings |
Permission Errors
| Error | Cause | Solution |
|---|
| "Insufficient permissions" | Token lacks required scope | Create a token with the needed scope |
Validation Errors
| Error | Cause | Solution |
|---|
| "title is required" | Missing required field | Include the title field |
| "steps must have at least 1 item" | Empty steps array | Add at least one step |
| "Invalid task_id format" | Non-UUID task_id | Use a valid UUID or omit for auto-generation |
State Errors
| Error | Cause | Solution |
|---|
| "Task is not pending" | Trying to cancel a completed task | Only cancel tasks with pending status |
| "Task not found" | Invalid ID or org mismatch | Verify the task_id and that your token belongs to the correct org |