本文へスキップ
バージョン: 11.x

エラー処理

プロシージャでエラーが発生すると、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コードで応答するエラーコードのリストを定義しています。

コード説明HTTPコード
BAD_REQUESTクライアントエラーと見なされる何らかの理由により、サーバーはリクエストを処理できません。400
UNAUTHORIZED要求されたリソースに対して有効な認証資格情報がないため、クライアントのリクエストが完了しませんでした。401
FORBIDDENサーバーは、REST APIなど、必要なデータソースへのアクセスが許可されていませんでした。403
NOT_FOUNDサーバーは要求されたリソースを見つけることができません。404
TIMEOUTサーバーは、この未使用の接続をシャットダウンしたいと考えています。408
CONFLICTサーバーのリクエストリソースが、ターゲットリソースの現在の状態と競合しています。409
PRECONDITION_FAILEDターゲットリソースへのアクセスが拒否されました。412
PAYLOAD_TOO_LARGEリクエストエンティティが、サーバーによって定義された制限を超えています。413
METHOD_NOT_SUPPORTEDサーバーはリクエストメソッドを知っていますが、ターゲットリソースはこのメソッドをサポートしていません。405
UNPROCESSABLE_CONTENTサーバーはリクエストメソッドを理解しており、リクエストエンティティも正しいのですが、処理できませんでした。422
TOO_MANY_REQUESTSレート制限を超過したか、サーバーに送信されているリクエストが多すぎます。429
CLIENT_CLOSED_REQUESTリソースへのアクセスが拒否されました。499
INTERNAL_SERVER_ERROR指定されていないエラーが発生しました。500

tRPCは、エラーからHTTPコードを抽出するのに役立つヘルパー関数 `getHTTPStatusCodeFromError` を公開しています。

ts
import { getHTTPStatusCodeFromError } from '@trpc/server/http';
 
// Example error you might get if your input validation fails
const error: TRPCError = {
  name: 'TRPCError',
  code: 'BAD_REQUEST',
  message: '"password" must be at least 4 characters',
};
 
if (error instanceof TRPCError) {
  const httpCode = getHTTPStatusCodeFromError(error);
  console.log(httpCode); // 400
}
ts
import { getHTTPStatusCodeFromError } from '@trpc/server/http';
 
// Example error you might get if your input validation fails
const error: TRPCError = {
  name: 'TRPCError',
  code: 'BAD_REQUEST',
  message: '"password" must be at least 4 characters',
};
 
if (error instanceof TRPCError) {
  const httpCode = getHTTPStatusCodeFromError(error);
  console.log(httpCode); // 400
}
ヒント

これをNext.js APIエンドポイントで使用する方法の完全な例は、サーバーサイドコールドキュメントにあります。

エラーの発生​

tRPCは、プロシージャ内で発生したエラーを表すために使用できるエラーサブクラス `TRPCError` を提供しています。

たとえば、このエラーを発生させると

server.ts
ts
import { initTRPC, TRPCError } from '@trpc/server';
const t = initTRPC.create();
const appRouter = t.router({
  hello: t.procedure.query(() => {
    throw new 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 { initTRPC, TRPCError } from '@trpc/server';
const t = initTRPC.create();
const appRouter = t.router({
  hello: t.procedure.query(() => {
    throw new 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(opts) {
    const { error, type, path, input, ctx, req } = opts;
    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(opts) {
    const { error, type, path, input, ctx, req } = opts;
    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
}