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

# Errors

> Status codes and error response shape for Public API v1

# Errors

## Status codes (public v1)

| Status | Meaning                  | Typical cause                                       |
| ------ | ------------------------ | --------------------------------------------------- |
| `200`  | Success                  | Valid key and query                                 |
| `400`  | Invalid query parameters | Zod validation failed (`limit`, `status`, dates, …) |
| `401`  | Unauthorized             | Missing header, wrong format, invalid/expired key   |
| `500`  | Internal server error    | Unexpected server failure                           |

Public v1 list routes do **not** currently return `403` for plan gates on the **read** path (auth is “valid key → org data”). Plan gating applies when **creating** API keys in the dashboard (`apiAccessEnabled`).

## Error body

```json theme={null}
{
  "error": "Unauthorized",
  "message": "API key required in Authorization header"
}
```

Validation failures may include structured Zod issues:

```json theme={null}
{
  "error": "Invalid query parameters",
  "details": [
    {
      "code": "too_big",
      "maximum": 100,
      "type": "number",
      "path": ["limit"],
      "message": "Number must be less than or equal to 100"
    }
  ]
}
```

OpenAPI schema: `publicErrorSchema` (`error`, optional `message`, optional `details`).

## Client guidance

| Situation      | Action                                                                |
| -------------- | --------------------------------------------------------------------- |
| `401`          | Fix key configuration; do not retry blindly                           |
| `400`          | Fix query params; do not retry the same payload                       |
| `500`          | Retry with exponential backoff; log `requestId` if you have edge logs |
| Network errors | Retry with backoff; make sync jobs idempotent                         |

Always check HTTP status **before** assuming a `data` array exists.