Clickup Common Errors

ClickUp Common Errors

Overview

Reference for ClickUp API v2 errors. All errors return JSON with err (message) and optionally ECODE (error code).

Error Response Format

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

HTTP Status Errors

400 Bad Request

401 Unauthorized — OAuth Errors

# 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}`);
  }
}

Prerequisites

• Authorized access to the affected environment and a scoped diagnostic identity
• Redacted request/correlation metadata and last certified integration state
• A known owner for workspace, token, task data, and production change approval
• Access to rate-limit and platform-status information

Instructions

Identify the target workspace/list and error class, collect only the minimum redacted response metadata, then apply the matching recovery path. Change one variable at a time and preserve the prior certified state; do not retry 401, 403, 429, or data-integrity errors with broader credentials or unbounded loops.

Error Handling

Output

Produce a diagnostic record with environment, affected resource ID, symptom, safe correlation data, containment action, retry/rollback decision, and escalation owner. Never include tokens, full task content, attachments, or unapproved member data in general logs or tickets.

Examples

On a 429, capture the reset header and defer the same idempotent job; do not submit a duplicate task. On a 401, halt the worker and verify the secret reference with its owner. If a mapping is wrong, compare the certified target state before retrying rather than overwriting tasks.

Resources

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

Next Steps

For comprehensive debugging, see clickup-debug-bundle.