SQLSTATE 错误速查
用稳定的五字符状态码诊断约束、事务、权限、资源和连接问题
应用应分支处理 SQLSTATE，不要匹配可能随版本和语言变化的错误文本。
高频状态码
| SQLSTATE | 名称 | 常见含义 | 稳妥动作 |
|---|---|---|---|
23505 | unique_violation | 唯一键冲突 | 返回冲突或使用明确的 ON CONFLICT 语义 |
23503 | foreign_key_violation | 引用不存在/仍被引用 | 修正操作顺序，不要临时禁用约束 |
23502 | not_null_violation | 必填列缺失 | 修正输入或迁移顺序 |
23514 | check_violation | 违反 CHECK | 解释业务边界，修正值 |
22P02 | invalid_text_representation | 类型转换失败 | 在应用边界校验并绑定正确类型 |
40001 | serialization_failure | 并发下无法保持隔离保证 | 回滚并重试整个事务 |
40P01 | deadlock_detected | 形成等待环 | 回滚整事务；统一锁顺序 |
55P03 | lock_not_available | NOWAIT/lock timeout | 稍后重试或返回冲突 |
57014 | query_canceled | statement timeout 或取消 | 区分主动取消与超时，优化或缩小请求 |
25P02 | in_failed_sql_transaction | 当前事务此前已失败 | ROLLBACK；不要继续发业务 SQL |
42501 | insufficient_privilege | 对对象或动作无权限 | 修正 grant/owner；不要提升为 superuser |
42P01 | undefined_table | 表不存在或 search path 错 | 核对 database/schema/迁移版本 |
42703 | undefined_column | 列不存在 | 核对 schema 契约与部署版本 |
53300 | too_many_connections | 连接槽耗尽 | 检查池配置、泄漏、保留管理连接 |
57P03 | cannot_connect_now | 启动、恢复或关闭中 | 带上限退避，检查实例状态 |
08006 | connection_failure | 连接已失败 | 判断事务结果是否未知，再安全重试 |
事务失败后的规则
事务内任意语句失败后，通常进入 aborted 状态：
ERROR: current transaction is aborted...
SQLSTATE: 25P02必须 ROLLBACK，或回滚到失败前创建的 savepoint。不要继续发送语句期待自动恢复。
重试分类
- 可整事务重试：
40001、40P01；使用次数上限、指数退避和 jitter。 - 可能短暂重试：
55P03、57P03、部分08***；先确认幂等和事务提交状态。 - 输入/模型错误，不应盲重试：
22***、23***、42***、42501。 - 资源问题：
53300、磁盘满、内存问题；重试会放大故障，先降载和修复容量。
诊断上下文
记录 SQLSTATE、约束/表/列名、数据库与 schema、应用版本、迁移版本、事务 ID/请求 ID、参数类型（敏感值脱敏）和是否已提交。驱动通常提供结构化错误字段，应直接读取。
AI 工具的返回
{
"ok": false,
"sqlstate": "23505",
"category": "constraint",
"retryable": false,
"constraint": "customers_email_unique",
"message_safe": "A customer with this email already exists"
}不要把原始数据库错误无过滤地返回终端用户；它可能泄露对象名、路径或数据片段。
Last updated on