Error Reference
All Alana API endpoints return errors in a consistent JSON envelope:
{
"error": {
"code": "AUTH_001",
"message": "Missing API key",
"request_id": "req_abc123"
}
}
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 |
Rate limit headers are included on every response: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.
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. 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:
{"error":"Upstream catalog service unavailable","code":"STREAM_ERROR"}
error key.
