> For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt.

# 4-Digit Business Error Codes

All Yearning v4 API endpoints return `{"err_code": <int>, "message": "...", "data": ...}`. Non-zero codes map to 8 stable domains (`10xx`–`70xx`).

| Prefix     | Domain                                        | Key Codes                                                                                                                                                                                                                                                             |
| :--------- | :-------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`10xx`** | Validation, Concurrency, Idempotency & Quotas | `1001 VALIDATION_FAILED`, `1002 RESOURCE_NOT_FOUND`, `1003 VERSION_CONFLICT`, `1007 IDEMPOTENCY_KEY_REUSED`, `1011 PRECONDITION_REQUIRED` (needs `Assess` `impact_token`), `1012 SYSTEM_CAPACITY_EXHAUSTED`                                                           |
| **`11xx`** | Identity & Reference Guards                   | `1101 INVALID_CREDENTIALS`, `1102 ADMIN_PASSWORD_LOCKED` (recover via `./Yearning --reset-admin-password`), `1103 ADMIN_IMMUTABLE`, `1104 USER_HAS_ACTIVE_ORDERS`, `1109 PASSWORD_MANAGED_BY_IDENTITY_SOURCE`                                                         |
| **`20xx`** | AI Precheck, Budget & Submission Gate         | `2001 REVIEW_OUTDATED`, `2002 SQL_BATCH_TOO_LARGE`, `2003 SQL_PARSE_FAILED`, `2005 SQL_ANONYMIZATION_FAILED`, `2006 TOO_MANY_FINGERPRINTS`, `2008 REVIEW_BLOCKED_BY_RISK`, `2010 AI_DAILY_BUDGET_EXHAUSTED`, `2011 AI_PROVIDER_FAILED`, `2013 SUBMISSION_GATE_FAILED` |
| **`30xx`** | Approval, Execution & `gh-ost`                | `3001 NOT_FROZEN_ACTOR`, `3002 APPROVAL_ALREADY_DECIDED`, `3005 EXECUTION_RESULT_UNKNOWN`, `3008 OUTSIDE_EXECUTION_WINDOW`, `3010 DATASOURCE_UNAVAILABLE`, `3011 GH_OST_UNSUPPORTED`, `3012 MANUAL_VERIFICATION_EVIDENCE_REQUIRED`                                    |
| **`40xx`** | Query Workspace & Grants                      | `4001 QUERY_GRANT_REQUIRED`, `4003 QUERY_EXPORT_NOT_GRANTED`, `4004 QUERY_GRANT_REVOKED`, `4007 QUERY_ONLY_SINGLE_SELECT`, `4009 QUERY_TIMEOUT`, `4010 QUERY_CURSOR_INVALID`, `4011 QUERY_STATEMENT_REJECTED`                                                         |
| **`50xx`** | Legacy v3 -> v4 Migration                     | `5001 MIGRATION_ACTIVE_WORK_EXISTS`, `5002 MIGRATION_DRY_RUN_REQUIRED`, `5003 MIGRATION_MAPPING_UNCONFIRMED`, `5005 MIGRATION_INVARIANT_FAILED`                                                                                                                       |
| **`60xx`** | Database AI Assistant                         | `6001 ASSISTANT_OUT_OF_SCOPE`, `6002 ASSISTANT_DATASOURCE_FORBIDDEN`, `6003 ASSISTANT_ANONYMIZATION_FAILED`, `6004 ASSISTANT_SQL_RESTORATION_INVALID`, `6005 ASSISTANT_DRAFT_REVISION_STALE`, `6006 ASSISTANT_CONTEXT_BUDGET_EXCEEDED`                                |
| **`70xx`** | SQL Performance Diagnostics                   | `7001 DIAGNOSTICS_DATASOURCE_FORBIDDEN`, `7004 DIAGNOSTICS_STATS_EXTENSION_DISABLED`, `7005 DIAGNOSTICS_INSUFFICIENT_DB_PRIVILEGES`, `7006 DIAGNOSTICS_SNAPSHOT_RATE_LIMITED`, `7007 DIAGNOSTICS_CIRCUIT_BREAKER_OPEN`                                                |
