> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneperfectslice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Every error the OnePerfectSlice API can return — error envelope shape, HTTP status codes, error code reference, and how to handle each one.

When a request fails, the OnePerfectSlice API returns a JSON object with a machine-readable `code` and a human-readable `message`:

```json theme={null}
{
  "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](/api/filters) for valid values |
| **401** | Unauthorized — missing or invalid API key        | Check your key; see [Authentication](/api/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](/api/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 |

<Note>
  Resources in a different organization always return 404 — never 403 — so you can't determine whether a resource exists outside your org.
</Note>

### 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 |