code and a human-readable message:
{
"error": {
"code": "INVALID_FILTERS",
"message": "Filter validation failed",
"details": {
"field": "crmDealStages",
"maxAllowed": 100,
"validValuesEndpoint": "/api/public/v1/filters/crm-deal-stages"
}
}
}
| Field | Type | What it contains |
|---|---|---|
code | string | Machine-readable identifier in UPPER_SNAKE_CASE |
message | string | Plain-English explanation of what went wrong |
details | object or null | Additional context when available (e.g., which field failed, valid alternatives) |
HTTP status codes
| Status | What it means | What to do |
|---|---|---|
| 200 | Success | — |
| 202 | Accepted — an async slice run has started | Poll GET /slice-runs/{id} for results |
| 400 | Bad request — invalid parameters or filters | Fix the request body; check filter endpoints for valid values |
| 401 | Unauthorized — missing or invalid API key | Check your key; see Authentication |
| 403 | Forbidden — usage limit exceeded | Wait for your billing cycle to reset or contact support |
| 404 | Resource not found | Verify the ID and that your key has access to this team’s data |
| 409 | Conflict — idempotency mismatch or run not ready | Use a new idempotency key, or wait for the run to complete |
| 429 | Concurrency limit exceeded | Wait for active runs to finish; see Rate Limiting |
| 503 | Timeout or temporary unavailability | Retry with exponential backoff (1s → 2s → 4s) |
Error code reference
Authentication (401)
| Code | When it happens |
|---|---|
MISSING_TOKEN | No Authorization: Bearer header in the request |
INVALID_TOKEN | The key doesn’t match any active token |
TOKEN_REVOKED | An Org Admin revoked this key |
TOKEN_EXPIRED | The key has passed its expiration date |
Validation (400)
| Code | When it happens |
|---|---|
INVALID_REQUEST | The request body isn’t valid JSON |
INVALID_FILTERS | One or more filter values are invalid |
DATE_RANGE_TOO_WIDE | Date range exceeds the 90-day lookback limit |
FILTER_ARRAY_TOO_LARGE | A filter array has more than 100 items |
INVALID_IDEMPOTENCY_KEY | Idempotency key is empty or longer than 255 characters |
Not found (404)
| Code | When it happens |
|---|---|
SLICE_NOT_FOUND | No slice with this key exists for your team |
RUN_NOT_FOUND | No run with this ID exists or it belongs to a different org |
Resources in a different organization always return 404 — never 403 — so you can’t determine whether a resource exists outside your org.
Conflict (409)
| Code | When it happens |
|---|---|
IDEMPOTENCY_KEY_CONFLICT | You reused an idempotency key with different arguments |
RUN_NOT_COMPLETED | You requested evidence for a run that hasn’t finished yet |
Limits (403 / 429)
| Code | Status | When it happens |
|---|---|---|
USAGE_LIMIT_EXCEEDED | 403 | Your team’s monthly AI insights quota is exhausted |
CONCURRENT_RUN_LIMIT | 429 | Your team already has 5 active slice runs |
Timeouts (503)
| Code | When it happens |
|---|---|
PREVIEW_COUNT_TIMEOUT | Preview count query took too long — try narrowing your filters |
RUN_LIST_TIMEOUT | Run history query took too long |
RUN_LOOKUP_TIMEOUT | Run detail lookup took too long |
EVIDENCE_TIMEOUT | Evidence retrieval took too long |
POST_SEARCH_TIMEOUT | Post search took too long — try a shorter date range |
FILTER_LOOKUP_TIMEOUT | Filter lookup took too long |
BILLING_UNAVAILABLE | Usage gating service is temporarily down |
IDEMPOTENCY_KEY_IN_PROGRESS | Another request with this idempotency key is still being processed — retry in a few seconds |