Error Codes

Complete reference of 30 error codes across 11 categories returned by the Taxonomy Service.

Error response formatjson

{
  "error": {
    "code": "TAX_1000",
    "message": "The requested taxonomy was not found",
    "http": 404
  }
}

TaxonomyTAX_1000-1099

Code	HTTP	Name	Description	Resolution
`TAX_1000`	404	`TAXONOMY_NOT_FOUND`	The requested taxonomy was not found	Verify the taxonomy name exists for this tenant
`TAX_1001`	409	`TAXONOMY_ALREADY_EXISTS`	A taxonomy with this name already exists	Use a different name or update the existing taxonomy
`TAX_1002`	409	`TAXONOMY_LOCKED`	This taxonomy is currently locked by another user	Wait for the lock to be released or contact the lock holder
`TAX_1003`	409	`TAXONOMY_PUBLISHED`	Cannot modify a published taxonomy	Unpublish or create a new version first
`TAX_1004`	404	`TAXONOMY_VERSION_NOT_FOUND`	The requested taxonomy version was not found	Verify the version number or ID exists

Code	HTTP	Name	Description	Resolution
`TAX_1100`	404	`TAXONOMY_ITEM_NOT_FOUND`	The requested taxonomy item was not found	Verify the item key exists in the taxonomy
`TAX_1101`	409	`TAXONOMY_ITEM_ALREADY_EXISTS`	A taxonomy item with this key already exists	Use a different key or update the existing item
`TAX_1102`	400	`MAX_DEPTH_EXCEEDED`	Maximum hierarchy depth exceeded	Reduce nesting depth or increase the taxonomy maxDepth
`TAX_1103`	400	`CIRCULAR_REFERENCE`	Circular reference detected in taxonomy hierarchy	Check parentKey assignments for cycles
`TAX_1104`	400	`INVALID_PARENT`	Parent item not found in taxonomy	Verify the parentKey exists in the taxonomy

Code	HTTP	Name	Description	Resolution
`TAX_1200`	429	`QUOTA_EXCEEDED`	Quota limit exceeded for this operation	Upgrade subscription tier or wait for quota reset
`TAX_1201`	402	`INSUFFICIENT_CREDITS`	Insufficient AI credits to perform this operation	Purchase additional AI credits or use non-AI features

Code	HTTP	Name	Description	Resolution
`TAX_1300`	400	`BULK_IMPORT_FAILED`	Bulk import operation failed	Check import data format and structure
`TAX_1301`	400	`INVALID_IMPORT_FORMAT`	Invalid import file format	Use supported formats: json, csv, excel
`TAX_1302`	400	`IMPORT_VALIDATION_FAILED`	Import data validation failed	Review validation errors in response and fix data

Code	HTTP	Name	Description	Resolution
`TAX_1400`	401	`UNAUTHORIZED`	Authentication required	Provide a valid JWT token in Authorization header
`TAX_1401`	403	`FORBIDDEN`	Insufficient permissions	Request required role from admin
`TAX_1402`	401	`INVALID_TOKEN`	Invalid or expired authentication token	Obtain a fresh JWT token
`TAX_1403`	403	`MISSING_PERMISSIONS`	Required permissions are missing	Request the necessary permissions from admin

Code	HTTP	Name	Description	Resolution
`TAX_1500`	400	`VALIDATION_FAILED`	Request validation failed	Check request body against API docs
`TAX_1501`	400	`INVALID_INPUT`	Invalid input provided	Review field constraints (type, min/max, pattern)
`TAX_1502`	400	`MISSING_REQUIRED_FIELD`	Required field is missing	Add the required field to the request body

Code	HTTP	Name	Description	Resolution
`TAX_1600`	502	`AI_SERVICE_ERROR`	AI service encountered an error	Retry; AI service may be temporarily unavailable
`TAX_1601`	502	`AI_SUGGESTION_FAILED`	Failed to generate AI suggestions	Check AI credits and retry
`TAX_1602`	502	`AI_COVERAGE_ANALYSIS_FAILED`	Failed to analyze taxonomy coverage	Retry; ensure taxonomy has items to analyze
`TAX_1603`	502	`AI_DUPLICATE_DETECTION_FAILED`	Failed to detect duplicate items	Retry; ensure taxonomy has items to compare

Code	HTTP	Name	Description	Resolution
`TAX_1700`	429	`RATE_LIMIT_EXCEEDED`	Rate limit exceeded	Wait and retry after the rate limit window resets
`TAX_1701`	429	`TOO_MANY_REQUESTS`	Too many requests in a short time period	Implement exponential backoff in client

Code	HTTP	Name	Description	Resolution
`TAX_1800`	502	`EXTERNAL_SERVICE_ERROR`	External service error	Retry; the downstream service may be temporarily unavailable
`TAX_1801`	502	`AIBRAIN_SERVICE_ERROR`	AI Brain service unavailable	Retry; aibrain-svc may be restarting on ECS Fargate
`TAX_1802`	502	`WALLET_SERVICE_ERROR`	Wallet service unavailable	Retry; wallet-svc may be temporarily unavailable
`TAX_1803`	502	`I18N_SERVICE_ERROR`	Internationalization service unavailable	Retry; i18n-svc may be temporarily unavailable
`TAX_1804`	502	`RAG_SERVICE_ERROR`	RAG service unavailable	Retry; rag-svc may be restarting on ECS Fargate

Code	HTTP	Name	Description	Resolution
`TAX_1900`	500	`DATABASE_ERROR`	Database operation failed	Retry; Aurora Serverless may be scaling up
`TAX_1901`	500	`TRANSACTION_FAILED`	Database transaction failed	Retry the operation
`TAX_1902`	409	`CONSTRAINT_VIOLATION`	Database constraint violation	Check for unique constraint conflicts

Code	HTTP	Name	Description	Resolution
`TAX_2000`	500	`INTERNAL_SERVER_ERROR`	Internal server error	Retry; if persistent, contact support with request_id
`TAX_2001`	503	`SERVICE_UNAVAILABLE`	Service temporarily unavailable	Retry with exponential backoff
`TAX_2002`	504	`TIMEOUT`	Request timeout	Reduce request complexity or retry