Clari Common Errors

Overview

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

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}'

Resources

• Clari Developer Portal
• Clari Community

Next Steps

For comprehensive diagnostics, see

clari-debug-bundle

.