Skip to content
Skills Library
Programming · Analysis

clickup-common-errors

/clickup-common-errors

Analyze and diagnose ClickUp authentication, authorization, plan, request, pagination, throttling, webhook, and provider failures from redacted evidence. Use when a ClickUp integration fails or behaves inconsistently. Trigger with "ClickUp error", "ClickUp 429", or "diagnose ClickUp API".

Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Analyze and diagnose ClickUp authentication, authorization, plan, request, pagination, throttling, webhook, and provider failures from redacted evidence. Use when a ClickUp integration fails or behaves inconsistently. Trigger with "ClickUp error", "ClickUp 429", or "diagnose ClickUp API".

Triggers from the description

ClickUp errorClickUp 429diagnose ClickUp API

Arguments

/clickup-common-errors [status-code-or-error] [endpoint]
Original author description

Analyze and diagnose ClickUp authentication, authorization, plan, request, pagination, throttling, webhook, and provider failures from redacted evidence. Use when a ClickUp integration fails or behaves inconsistently. Trigger with "ClickUp error", "ClickUp 429", or "diagnose ClickUp API".

How it works

  1. Overview
  2. Prerequisites
  3. Tool Discipline
  4. Current Contract
  5. Authentication
  6. Instructions
  7. Approval Boundaries
  8. Output
  9. Error Handling
  10. Examples
Original SKILL.md headings · 68 lines, 449 words
SKILL.md preview
---
name: clickup-common-errors
description: >-
  Analyze and diagnose ClickUp authentication, authorization, plan, request, pagination, throttling, webhook, and provider failures from redacted evidence. Use when a ClickUp integration fails or behaves inconsistently. Trigger with "ClickUp error", "ClickUp 429", or "diagnose ClickUp API".
argument-hint: "[status-code-or-error] [endpoint]"
allowed-tools: Read, Glob, Grep, WebFetch, Write, Edit
version: 1.8.0
author: Jeremy Longshore <jeremy@intentsolutions.io>
license: MIT
tags:
- saas
- clickup
- troubleshooting
model: inherit
effort: high
compatibility: Designed for Claude Code; live diagnosis requires authorized ClickUp access and sanitized evidence
---
# ClickUp Error Diagnosis

## Overview

Classify the failure before changing code so authentication, workspace scope, plan gates, schema drift, and transient provider faults receive different remedies.

## Prerequisites

- A redacted status code, ClickUp error code/message, endpoint version, and request shape
- The authorized Workspace ID, auth mode, and current plan facts from an owner
- Access to current ClickUp docs and status information

## Tool Discipline

Use `Read`, `Glob`, and `Grep` to inspect the repository, adapters, configuration names, tests, and evidence. Use `WebFetch` only for current official ClickUp documentation. Use `Write` or `Edit` after confirming the target file, Workspace boundary, and requested mode.

## Current Contract

- `OAUTH_017` can indicate a missing Authorization header; workspace authorization and revoked-token families have distinct codes.
- Browser-side CORS failures require a server-side boundary, not a permissive token-bearing frontend workaround.
- A 429 is per token; inspect `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and Unix `X-RateLimit-Reset`.
- Retry only bounded transient failures; do not retry malformed requests or permission denials.

## Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in `Authorization`, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

## Instructions

1. Capture the method, versioned path, status, ClickUp error code, response type, and sanitized headers.
2. Confirm whether the caller uses a personal token or OAuth and whether the Workspace was authorized.
3. Validate path parameters, JSON content type, endpoint version, pagination cursor/page, and plan eligibility.
4. Separate 401/403, 404, 409-style state conflicts, 429, timeout, and 5xx classes.
5. Reproduce with the smallest read-only request and compare against the official reference.
6. Recommend the narrowest correction and record the post-fix probe.

## Approval Boundaries

Do not regenerate credentials, reauthorize Workspaces, upgrade a plan, replay writes, or disclose task content merely to diagnose an error.

## Output

Return failure class, evidence, likely cause, safe correction, retry decision, owner action, and verification result.

## Error Handling

| Condition | Response |
|---|---|
| Evidence contains a token or work content | Stop, redact it, and rotate the exposed credential if necessary. |
| Workspace scope is unknown | Do not infer permission; obtain authorized Workspace facts. |
| 429 lacks usable reset data | Pause with bounded backoff and re-probe conservatively. |
| Provider status is degraded | Defer writes and retain the incident window. |

## Examples

The example below is a redacted operator receipt; it contains no task text, member data, credential, or webhook secret.

```text
status=401; code=OAUTH_017; class=auth-header; retry=no; correction=restore-server-secret-reference
```

## Resources

- [Skill-specific official documentation](references/official-docs.md)
- [Common errors](https://developer.clickup.com/docs/common_errors)
- [Authentication](https://developer.clickup.com/docs/authentication)
- [Rate limits](https://developer.clickup.com/docs/rate-limits)
Files in this package (2)
  • SKILL.md 4 KB
  • references/official-docs.md 2 KB

Versions

The database has no other skills named clickup-common-errors.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 8d680dc16403 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100together-common-errors
    Analyze and diagnose Together AI authentication, billing, request, model, throttling, overload, batch, fine-tuning, and endpoint failures from redacted evidence. Use when a Together integration fails or behaves inconsistently. Trigger with "Together error", "Together 429", or…
  • 100clickup-webhooks
    Receive and verify ClickUp webhooks. Use when setting up ClickUp webhook handlers, debugging X-Signature verification, or handling ClickUp events like taskCreated, taskUpdated, taskStatusUpdated, or taskCommentPosted.
  • 100clickup-rate-limits
    Analyze and control ClickUp request concurrency from plan-aware per-token limits, response headers, bounded queues, and reset-based retries. Use when preventing or recovering from ClickUp 429 responses. Trigger with "ClickUp rate limit", "ClickUp 429", or "size ClickUp concurrency".
  • 100testing-clickup-cli
    Run and manage tests for clickup-cli. Covers unit tests, e2e tests against a real ClickUp workspace, and the test data setup. Use when running tests, adding test coverage, debugging test failures, or setting up test fixtures.
  • 100clickup
    Interact with ClickUp tasks - get task details, view comments, create and manage tasks. Use when working with ClickUp task URLs or IDs.
  • 90ClickUp Task Workflow
    This skill should be used when the user mentions "ClickUp task", "CU-xxx", "task workflow", "clickup integration", or when working with task plugin commands (/task:start, /task:done, /task:merge, /task:status, /task:new). Provides workflow patterns for ClickUp task management integrated with kas.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.