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

# Errors

> HTTP status codes and error response shapes.

## Error response format

All errors return JSON with at minimum a `message` field:

```json theme={null}
{
  "message": "Brand not found",
  "code": "not_found"
}
```

Some errors include additional context fields (see per-endpoint docs).

## Status codes

| Code  | Meaning               | Common causes                                                                                       |
| ----- | --------------------- | --------------------------------------------------------------------------------------------------- |
| `200` | OK                    | Request succeeded.                                                                                  |
| `201` | Created               | Resource was created (write endpoints).                                                             |
| `400` | Bad Request           | Missing or invalid request body / parameters.                                                       |
| `401` | Unauthorized          | Missing or invalid API key.                                                                         |
| `403` | Forbidden             | Feature disabled for your plan or organization.                                                     |
| `404` | Not Found             | Brand, run, topic, or prompt doesn't exist — or doesn't belong to your organization.                |
| `405` | Method Not Allowed    | HTTP method is not supported on this path.                                                          |
| `409` | Conflict              | Prompt limit exceeded. Response includes `code: "prompt_limit_exceeded"` and remaining slot counts. |
| `429` | Too Many Requests     | Rate limit exceeded. Back off and retry.                                                            |
| `500` | Internal Server Error | Unexpected server-side failure. Server logs are tagged `[org-api]`.                                 |

## 404 — unknown path

When the path doesn't match any route, the API returns a helpful `404` with the normalized path and the full list of available endpoints:

```json theme={null}
{
  "message": "Endpoint not found",
  "path": "/v1/brandz",
  "availableEndpoints": [
    { "method": "GET", "path": "/v1/brands" },
    { "method": "GET", "path": "/v1/brands/{brandId}/runs" }
  ]
}
```

## 409 — prompt limit exceeded

```json theme={null}
{
  "message": "Prompt limit exceeded",
  "code": "prompt_limit_exceeded",
  "remainingSlots": 0,
  "promptLimit": 100,
  "orgWideLimit": 500,
  "orgTotalPrompts": 500
}
```

## 403 — feature disabled

```json theme={null}
{
  "message": "Custom perception prompts are not enabled for this organization",
  "code": "custom_perception_prompts_disabled"
}
```