版本：9.x

错误处理

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。发现错误？报告问题 →

当某个过程中发生错误时，tRPC 会向客户端返回包含 "error" 属性的响应对象。该属性包含你在客户端处理错误所需的全部信息。

以下是由无效请求输入导致的错误响应示例：

json
{
  "id": null,
  "error": {
    "message": "\"password\" must be at least 4 characters",
    "code": -32600,
    "data": {
      "code": "BAD_REQUEST",
      "httpStatus": 400,
      "stack": "...",
      "path": "user.changepassword"
    }
  }
}

json
{
  "id": null,
  "error": {
    "message": "\"password\" must be at least 4 characters",
    "code": -32600,
    "data": {
      "code": "BAD_REQUEST",
      "httpStatus": 400,
      "stack": "...",
      "path": "user.changepassword"
    }
  }
}

错误代码

tRPC 定义了一组错误代码，每个代码代表不同类型的错误，并对应不同的 HTTP 状态码。

Code	Description	HTTP code
BAD_REQUEST	The server cannot or will not process the request due to something that is perceived to be a client error.	400
UNAUTHORIZED	The client request has not been completed because it lacks valid authentication credentials for the requested resource.	401
FORBIDDEN	The server was unauthorized to access a required data source, such as a REST API.	403
NOT_FOUND	The server cannot find the requested resource.	404
TIMEOUT	The server would like to shut down this unused connection.	408
CONFLICT	The server request resource conflict with the current state of the target resource.	409
PRECONDITION_FAILED	Access to the target resource has been denied.	412
PAYLOAD_TOO_LARGE	Request entity is larger than limits defined by server.	413
METHOD_NOT_SUPPORTED	The server knows the request method, but the target resource doesn't support this method.	405
CLIENT_CLOSED_REQUEST	Access to the resource has been denied.	499
INTERNAL_SERVER_ERROR	An unspecified error occurred.	500

抛出错误

tRPC 提供了 TRPCError 错误子类，用于表示在过程中发生的错误。

例如，抛出以下错误：

server.ts
ts
import * as trpc from '@trpc/server';
const appRouter = trpc.router().query('hello', {
  resolve: () => {
    throw new trpc.TRPCError({
      code: 'INTERNAL_SERVER_ERROR',
      message: 'An unexpected error occurred, please try again later.',
      // optional: pass the original error to retain stack trace
      cause: theError,
    });
  },
});
// [...]

server.ts
ts
import * as trpc from '@trpc/server';
const appRouter = trpc.router().query('hello', {
  resolve: () => {
    throw new trpc.TRPCError({
      code: 'INTERNAL_SERVER_ERROR',
      message: 'An unexpected error occurred, please try again later.',
      // optional: pass the original error to retain stack trace
      cause: theError,
    });
  },
});
// [...]

将产生如下响应：

json
{
  "id": null,
  "error": {
    "message": "An unexpected error occurred, please try again later.",
    "code": -32603,
    "data": {
      "code": "INTERNAL_SERVER_ERROR",
      "httpStatus": 500,
      "stack": "...",
      "path": "hello"
    }
  }
}

json
{
  "id": null,
  "error": {
    "message": "An unexpected error occurred, please try again later.",
    "code": -32603,
    "data": {
      "code": "INTERNAL_SERVER_ERROR",
      "httpStatus": 500,
      "stack": "...",
      "path": "hello"
    }
  }
}

错误处理

过程中发生的所有错误在发送到客户端前都会经过 onError 方法处理，你可以在该方法中修改或处理错误。

pages/api/trpc/[trpc].ts
ts
export default trpcNext.createNextApiHandler({
  // ...
  onError({ error, type, path, input, ctx, req }) {
    console.error('Error:', error);
    if (error.code === 'INTERNAL_SERVER_ERROR') {
      // send to bug reporting
    }
  },
});

pages/api/trpc/[trpc].ts
ts
export default trpcNext.createNextApiHandler({
  // ...
  onError({ error, type, path, input, ctx, req }) {
    console.error('Error:', error);
    if (error.code === 'INTERNAL_SERVER_ERROR') {
      // send to bug reporting
    }
  },
});

onError 参数是一个包含错误本身及其上下文所有信息的对象：

ts
{
  error: TRPCError; // the original error
  type: 'query' | 'mutation' | 'subscription' | 'unknown';
  path: string | undefined; // path of the procedure that was triggered
  input: unknown;
  ctx: Context | undefined;
  req: BaseRequest; // request object
}

ts
{
  error: TRPCError; // the original error
  type: 'query' | 'mutation' | 'subscription' | 'unknown';
  path: string | undefined; // path of the procedure that was triggered
  input: unknown;
  ctx: Context | undefined;
  req: BaseRequest; // request object
}

错误代码​

抛出错误​

错误处理​

错误代码

抛出错误

错误处理