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

# Error Reference

> Structured error codes for all Alana distribution channels — Canal 1 (Feed), Canal 2 (Search API), Canal 3 (MCP).

# Error Reference

All Alana API endpoints return errors in a consistent JSON envelope:

```json theme={null}
{
  "error": {
    "code": "AUTH_001",
    "message": "Missing API key",
    "request_id": "req_abc123"
  }
}
```

Use the `request_id` when contacting support to help us quickly locate your request in our logs.

***

## Authentication Errors

| Code       | HTTP | Message                  | Description                                        | Resolution                                                                    | Channels |
| ---------- | ---- | ------------------------ | -------------------------------------------------- | ----------------------------------------------------------------------------- | -------- |
| `AUTH_001` | 401  | Missing API key          | The request did not include an API key.            | Include your API key via `X-API-Key` header or `Authorization: Bearer <key>`. | All      |
| `AUTH_002` | 401  | Invalid API key          | The API key is not recognized or has been revoked. | Verify your key in Settings → API Keys. Generate a new key if needed.         | All      |
| `AUTH_003` | 403  | Insufficient permissions | The key does not have the required scopes.         | Update API key permissions in Settings → API Keys.                            | All      |
| `AUTH_004` | 403  | Workspace access denied  | The key does not have access to this workspace.    | Contact your workspace owner to grant access.                                 | Canal 2  |

***

## Rate Limit Errors

| Code       | HTTP | Message                  | Description                                | Resolution                                                                  | Channels |
| ---------- | ---- | ------------------------ | ------------------------------------------ | --------------------------------------------------------------------------- | -------- |
| `RATE_001` | 429  | Rate limit exceeded      | Per-key rate limit exceeded.               | Check `X-RateLimit-Reset` header and slow down requests. Consider batching. | All      |
| `RATE_002` | 429  | Concurrent request limit | Too many concurrent requests from same IP. | Implement request queuing or distribute over longer windows.                | Canal 2  |

<Tip>
  Rate limit headers are included on every response: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`.
</Tip>

***

## Search Errors

| Code         | HTTP | Message                  | Description                                      | Resolution                                    | Channels |
| ------------ | ---- | ------------------------ | ------------------------------------------------ | --------------------------------------------- | -------- |
| `SEARCH_001` | 400  | Invalid query parameters | One or more search parameters failed validation. | Review the error detail in the response body. | Canal 2  |
| `SEARCH_002` | 400  | Query too long           | The query string exceeds 512 characters.         | Shorten the query.                            | Canal 2  |

***

## Feed Errors

| Code       | HTTP | Message                | Description                                               | Resolution                                                         | Channels         |
| ---------- | ---- | ---------------------- | --------------------------------------------------------- | ------------------------------------------------------------------ | ---------------- |
| `FEED_001` | 400  | Unsupported platform   | The platform is not supported or not configured.          | Check `GET /api/mcp/feed` for supported platforms.                 | Canal 1, Canal 3 |
| `FEED_002` | 404  | Feed not found         | No published catalog found for this workspace + platform. | Publish a catalog in the Alana dashboard first.                    | Canal 1          |
| `FEED_003` | 422  | Feed validation failed | Feed content failed platform-specific validation.         | Review validation errors. Use Optimization Score to fix data gaps. | Canal 1          |

***

## Catalog / Data Errors

| Code       | HTTP | Message              | Description                                             | Resolution                                         | Channels         |
| ---------- | ---- | -------------------- | ------------------------------------------------------- | -------------------------------------------------- | ---------------- |
| `DATA_001` | 404  | Product not found    | No product with the given ID in the workspace.          | Verify the product UUID. It may have been deleted. | All              |
| `DATA_002` | 404  | Catalog not found    | No catalog with the given ID in this workspace.         | Verify the catalog UUID in the dashboard.          | Canal 2, Canal 3 |
| `DATA_003` | 409  | Duplicate entity     | An entity with the same unique ID already exists.       | Use the update endpoint instead of create.         | Canal 2, Canal 3 |
| `DATA_004` | 422  | Invalid product data | Product data failed schema or business rule validation. | Review the `details` array in the error response.  | Canal 3          |

***

## MCP Errors

| Code      | HTTP | Message                 | Description                                          | Resolution                                          | Channels |
| --------- | ---- | ----------------------- | ---------------------------------------------------- | --------------------------------------------------- | -------- |
| `MCP_001` | 400  | Unknown tool            | The MCP tool name does not exist or is filtered out. | Use `GET /api/v1/manifest` to list available tools. | Canal 3  |
| `MCP_002` | 400  | Invalid tool parameters | Tool parameters failed schema validation.            | Check the tool's input schema in the MCP manifest.  | Canal 3  |

***

## Server Errors

| Code         | HTTP | Message               | Description                      | Resolution                                                                        | Channels |
| ------------ | ---- | --------------------- | -------------------------------- | --------------------------------------------------------------------------------- | -------- |
| `SERVER_001` | 500  | Internal server error | Unexpected server error.         | Retry with exponential backoff. Contact support with `request_id`.                | All      |
| `SERVER_002` | 503  | Service unavailable   | Service temporarily unavailable. | Check [status.alana.shopping](https://status.alana.shopping). Retry with backoff. | All      |

***

## NDJSON Error Lines

When using `Accept: application/x-ndjson` for streaming responses, errors mid-stream are emitted as a final NDJSON line:

```json theme={null}
{"error":"Upstream catalog service unavailable","code":"STREAM_ERROR"}
```

The stream closes after this line. Your client should check each line for an `error` key.