ClickUp Common Errors

Overview

Reference for ClickUp API v2 errors. All errors return JSON with

err

ECODE

Error Response Format

{
  "err": "Space not found",
  "ECODE": "ITEM_015"
}

HTTP Status Errors

400 Bad Request

{"err": "Task name required"}

name

{"err": "Invalid priority"}

{"err": "Unexpected token"}

{"err": "Invalid value for field"}

401 Unauthorized — OAuth Errors

Authorization: <token>

# Diagnose: verify your token works
curl -s -w "\nHTTP %{http_code}\n" \
  https://api.clickup.com/api/v2/user \
  -H "Authorization: $CLICKUP_API_TOKEN"

403 Forbidden

404 Not Found

# Common causes: wrong ID, deleted resource, wrong hierarchy level
# Verify the resource exists:
curl -s https://api.clickup.com/api/v2/task/TASK_ID \
  -H "Authorization: $CLICKUP_API_TOKEN" | jq '.id, .name'

429 Rate Limited

Rate limits vary by plan (per token, per minute):

• Free/Unlimited/Business: 100 req/min
• Business Plus: 1,000 req/min
• Enterprise: 10,000 req/min

# Check rate limit headers on any response
curl -s -D - https://api.clickup.com/api/v2/user \
  -H "Authorization: $CLICKUP_API_TOKEN" 2>&1 | grep -i ratelimit

# Headers returned:
# X-RateLimit-Limit: 100
# X-RateLimit-Remaining: 95
# X-RateLimit-Reset: 1695000060  (Unix timestamp)

500/503 Server Errors

Check ClickUp Status Page first.

# Quick status check
curl -s https://status.clickup.com/api/v2/summary.json | \
  jq '.status.description'

Diagnostic Script

#!/bin/bash
echo "=== ClickUp API Diagnostics ==="

# 1. Auth check
echo -n "Auth: "
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
  https://api.clickup.com/api/v2/user \
  -H "Authorization: $CLICKUP_API_TOKEN")
[ "$HTTP_CODE" = "200" ] && echo "OK" || echo "FAILED ($HTTP_CODE)"

# 2. Rate limit check
echo -n "Rate limit remaining: "
curl -s -D - https://api.clickup.com/api/v2/user \
  -H "Authorization: $CLICKUP_API_TOKEN" 2>&1 | \
  grep "X-RateLimit-Remaining" | awk '{print $2}'

# 3. Workspace access
echo "Workspaces:"
curl -s https://api.clickup.com/api/v2/team \
  -H "Authorization: $CLICKUP_API_TOKEN" | jq -r '.teams[] | "  \(.id): \(.name)"'

Error Handler Pattern

async function handleClickUpError(response: Response): Promise<never> {
  const body = await response.json().catch(() => ({ err: 'Unknown' }));

  switch (response.status) {
    case 401:
      throw new Error(`Auth failed (${body.ECODE}): Re-check token or re-authorize`);
    case 429: {
      const resetAt = response.headers.get('X-RateLimit-Reset');
      const waitMs = resetAt ? (parseInt(resetAt) * 1000 - Date.now()) : 60000;
      throw new Error(`Rate limited. Retry after ${Math.ceil(waitMs / 1000)}s`);
    }
    case 404:
      throw new Error(`Resource not found: ${body.err}`);
    default:
      throw new Error(`ClickUp API ${response.status}: ${body.err}`);
  }
}

Resources

• ClickUp Common Errors
• ClickUp API Error Handling
• ClickUp Status Page

Next Steps

For comprehensive debugging, see

clickup-debug-bundle