Errors
Understand Clics API HTTP error codes, error response format, and how to handle failed analytics requests.
The API returns standard HTTP status codes with a JSON error body:
{
"error": "Human-readable message",
"code": "ERROR_CODE"
}Common status codes
| Status | Meaning |
|---|---|
400 |
Invalid request body or parameters |
401 |
Missing or invalid API key |
403 |
Key valid but not allowed (including UPGRADE_REQUIRED on trial/unpaid workspaces) |
404 |
Resource not found |
429 |
Rate limit exceeded |
500 |
Server error. Retry with backoff |
503 |
Billing service temporarily unavailable (BILLING_UNAVAILABLE) |
Active trial or paid plan required
REST API calls require an active trial or paid subscription. After a trial expires without a paid subscription, responses look like:
{
"error": "API requires an active trial or paid plan",
"code": "UPGRADE_REQUIRED"
}Status: 403. Remote OAuth MCP remains available on every plan. See Billing for access details.
Validation errors
400 responses include details about which field failed validation when applicable.
MCP errors
MCP tools return errors as tool results with isError: true and a JSON message in content.