About

Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/clari-common-errors/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill clari-common-errors. Copyright stays with the author (MIT).

Clari Common Errors

Name: clari-common-errors
Author: jeremylongshore

Overview

Diagnostic guide for the most common Clari API issues: authentication failures, empty exports, job timeouts, and data discrepancies.

Prerequisites

Authorized, scoped access to the affected Clari environment
Redacted job IDs, timestamps, and export metadata for diagnosis
A named owner for credentials, forecast data, and production change approval
Access to the certified prior dataset for safe comparison and recovery

Instructions

Confirm the environment and affected period, collect the smallest redacted evidence needed to classify the issue, then follow the matching reference entry. Change one variable at a time and do not retry authentication, rate, or data-integrity failures indefinitely. Escalate ambiguous provider behavior with job IDs and timestamps rather than guessing at a production fix.

Error Handling

Failure class	Safe first response
Authentication or authorization	Stop retries and route to the credential/admin owner.
Empty, partial, or mismatched export	Mark the dataset uncertified and retain the prior certified output.
Timeout or rate limit	Preserve job state and resume through the bounded scheduler policy.
Suspected data exposure	Restrict access, notify governance, and use the incident process.

Error Reference

1. 401 Unauthorized

{"error": "Unauthorized", "message": "Invalid API key"}

Fix: Regenerate token at Clari > User Settings > API Token. Tokens may expire or be revoked by admins.

2. 403 Forbidden -- API Access Not Enabled

{"error": "Forbidden", "message": "API access not enabled for this user"}

Fix: Contact your Clari admin to enable API access. Requires enterprise plan.

3. 404 Forecast Not Found

{"error": "Not Found", "message": "Forecast 'wrong_name' not found"}

Fix: List available forecasts first:

curl -s -H "apikey: ${CLARI_API_KEY}" \
  https://api.clari.com/v4/export/forecast/list | jq '.forecasts[].forecastName'

4. Export Returns Empty Entries

The API returns {"entries": []} with no error.

Causes:

Time period has no submitted forecasts
User lacks visibility into the forecast hierarchy
Wrong forecast name (case-sensitive)

Fix: Verify in Clari UI that the forecast has submissions for the requested period.

5. Job Stuck in PENDING

Export job never reaches COMPLETED status.

Causes:

Very large export (all reps, all periods)
Clari backend queue congestion

Fix: Increase polling timeout. Break large exports into per-period batches.

6. Data Mismatch Between API and UI

Forecast numbers from API do not match what is shown in Clari UI.

Causes:

API exports submitted calls, UI may show latest-edited values
Currency conversion differences
Time period boundary differences (calendar vs fiscal)

Fix: Use includeHistorical: true to get all submission versions. Match the exact time period label from the UI.

7. Copilot API OAuth Errors

{"error": "invalid_client"}

Fix: The Copilot API uses OAuth2, not API key auth. Register your app at https://api-doc.copilot.clari.com and use client credentials flow.

8. Rate Limit Exceeded

HTTP 429 Too Many Requests

Fix: Implement exponential backoff. See clari-rate-limits for patterns.

Quick Diagnostic Commands

# Test API key
curl -s -o /dev/null -w "%{http_code}" \
  -H "apikey: ${CLARI_API_KEY}" \
  https://api.clari.com/v4/export/forecast/list

# List all forecasts
curl -s -H "apikey: ${CLARI_API_KEY}" \
  https://api.clari.com/v4/export/forecast/list | jq .

# Check running jobs
curl -s -H "apikey: ${CLARI_API_KEY}" \
  https://api.clari.com/v4/export/jobs | jq '.jobs[] | {jobId, status, createdAt}'

Output

Create a redacted incident record with environment, period, symptom, source job/correlation ID, evidence, containment action, current data-certification state, and escalation owner. Keep tokens, individual forecast values, and download URLs out of diagnostic tickets and chat.

Examples

When an export returns zero records, confirm the source period and job status, mark the downstream refresh failed, and retain yesterday’s certified dataset. When a request returns 401, stop the scheduler, verify the secret reference with its owner, and rotate through the approved process instead of testing keys in terminals or tickets.

Resources

Next Steps

For comprehensive diagnostics, see clari-debug-bundle.

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/jeremylongshore-tons-of-skills-marketplace-clari-common-errors/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

jeremylongshore-tons-of-skills-marketplace-clari-common-errors.ocm.jsonjson

{
  "ocm": "1",
  "id": "jeremylongshore-tons-of-skills-marketplace-clari-common-errors",
  "kind": "skill",
  "name": "clari-common-errors",
  "description": "Diagnose and fix Clari API errors including auth failures, export issues, and data mismatches. Use when Clari API calls fail, exports return empty data, or forecast numbers do not match the UI. Trigger with phrases like \"clari error\", \"clari not working\", \"clari api failure\", \"fix clari\", \"debug clari\".",
  "publisher": "jeremylongshore",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "coding",
      "customer_support"
    ],
    "tags": [
      "skill-md",
      "saas",
      "revenue-intelligence",
      "forecasting",
      "clari",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Diagnose and fix Clari API errors including auth failures, export issues, and data mismatches. Use when Clari API calls fail, exports return empty data, or forecast numbers do not match the UI. Trigger with phrases like \"clari error\", \"clari not working\", \"clari api failure\", \"fix clari\", \"debug clari\"."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/jeremylongshore/tons-of-skills-marketplace",
      "path": "skills/.curated/clari-common-errors/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/jeremylongshore/tons-of-skills-marketplace/blob/HEAD/skills/.curated/clari-common-errors/SKILL.md",
      "key": "jeremylongshore/tons-of-skills-marketplace/skills/.curated/clari-common-errors/SKILL.md"
    },
    "compatibility": "Designed for Claude Code",
    "allowed_tools": [
      "Read,",
      "Bash(curl:*),",
      "Grep"
    ],
    "license": "MIT"
  },
  "instructions": "# Clari Common Errors\n\n## Overview\n\nDiagnostic guide for the most common Clari API issues: authentication failures, empty exports, job timeouts, and data discrepancies.\n\n## Prerequisites\n\n- Authorized, scoped access to the affected Clari environment\n- Redacted job IDs, timestamps, and export metadata for diagnosis\n- A named owner for credentials, forecast data, and production change approval\n- Access to the certified prior dataset for safe comparison and recovery\n\n## Instructions\n\nConfirm the environment and affected period, collect the smallest redacted\nevidence needed to classify the issue, ",
  "cost": {
    "context_tokens": 1159
  }
}

Fetch it by URL: GET /api/v1/registry/jeremylongshore-tons-of-skills-marketplace-clari-common-errors/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.