> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# エラー

> GetQR API が返すエラーの形式とコード。

> [!NOTE]
>
> GetQR API はベータ版で、一部のワークスペースでのみご利用いただけます。正式リリースまでに内容が変更される場合があります。

GetQR API は標準の HTTP ステータスコードを使います。成功したリクエストは `2xx` を返します。失敗したリクエストは `4xx` または `5xx` を返し、何が問題だったかを説明する JSON ボディが付きます。

## エラーの形式

すべてのエラーは同じ形をしています。安定したコード、人が読めるメッセージ、そのコードの説明へのリンクです。

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized: Invalid API key.",
    "doc_url": "https://getqr.com/account/api-docs#error-unauthorized"
  }
}
```

**error.code** `string` *required*

安定した、機械で読み取れるエラーコード。コードではメッセージではなくこちらを使ってください。[エラーコード](#エラーコード) をご覧ください。

**error.message** `string` *required*

問題を説明する、人が読める文。文言は変わることがあります。

**error.doc\_url** `string` *required*

GetQR アカウント内の API ドキュメントで、このエラーコードの説明へのリンク。

## エラーコード

| コード | HTTP ステータス | 発生する状況 |
| - | - | - |
| `bad_request` | 400 | リクエストの形式が正しくありません。ボディが有効な JSON でない、`Authorization` ヘッダーに `Bearer ` プレフィックスがない、またはリソースの現在の状態ではその操作が許可されていない（例：完了した一括作成のキャンセル）場合です。 |
| `unauthorized` | 401 | API キーがないか無効です。たとえば、キーが再生成された場合です。 |
| `forbidden` | 403 | ワークスペースのオーナーのサブスクリプションが有効でないか、ワークスペースでのあなたの役割ではこの操作が許可されていません。 |
| `exceeded_limit` | 403 | プランの上限に達しました。Single QR プランで、ワークスペースにすでに QR コードが 1 つあるときに QR コードを作成または複製した場合や、一括作成を開始した場合です。 |
| `not_found` | 404 | リソースが存在しないかワークスペースにない、エンドポイントが存在しない、またはワークスペースで API が有効になっていません。 |
| `method_not_allowed` | 405 | エンドポイントは存在しますが、この HTTP メソッドは受け付けません。`Allow` ヘッダーに受け付けるメソッドが示されます。 |
| `conflict` | 409 | リクエストが既存のデータと競合しています。短縮リンクのスラッグが使用済み、同じ `Idempotency-Key` のリクエストが処理中、スケジュールが既存のものと重複している、または一括作成のアーカイブがまだ準備できていない場合です。 |
| `invite_pending` | 409 | ワークスペースに招待されていますが、まだ参加していません。API キーのリクエストではこのエラーは返りません。キーのワークスペースは、必ずあなたが所属しているワークスペースだからです。 |
| `invite_expired` | 410 | ワークスペースへの招待の有効期限が切れています。同じ理由で、API キーのリクエストではこのエラーは返りません。 |
| `unprocessable_entity` | 422 | ボディまたはクエリパラメータがバリデーションに失敗しました。メッセージには、フィールド名とその問題点が示されます。[バリデーションエラー](#バリデーションエラー) をご覧ください。 |
| `rate_limit_exceeded` | 429 | API キーが現在のウィンドウのリクエスト数を使い切りました。[レート制限](https://docs.getqr.com/ja/api/rate-limits.md) をご覧ください。 |
| `internal_server_error` | 500 | GetQR 側で問題が発生しました。しばらくしてから再試行し、問題が続く場合はサポートにお問い合わせください。 |

## バリデーションエラー

ボディまたはクエリパラメータがバリデーションに失敗すると、API は `422` を返します。メッセージは、最初に見つかった無効なフィールドを `<issue>: <field>: <details>` の形式で示します。

```json theme={null}
{
  "error": {
    "code": "unprocessable_entity",
    "message": "too_big: pageSize: Max page size is 100.",
    "doc_url": "https://getqr.com/account/api-docs#error-unprocessable_entity"
  }
}
```

ネストしたフィールドはドット記法で表します。例：`link.url`。

## エラーを処理する

* `error.message` ではなく `error.code` で分岐します。
* `4xx` エラーは、そのまま再試行せず、先にリクエストを修正してください。例外は、処理中のリクエストに対する `409` と、`429` です。
* `429` の場合は、`Retry-After` ヘッダーの秒数だけ待ちます。[制限を超えた場合](https://docs.getqr.com/ja/api/rate-limits.md#制限を超えた場合) をご覧ください。
* `5xx` エラーは指数バックオフで再試行します。

## よくある問題

> [accordion] すべてのリクエストで 404 "This endpoint is not available." が返る
>
> API はベータ版で、あなたのワークスペースではまだ有効になっていません。

> [accordion] 404 "This endpoint does not exist."
>
> パスが間違っています。エンドポイントのページと照らし合わせ、`/api/v1/` で始まっていることを確認してください。

> [accordion] 403 "Access denied: This account does not have an active subscription."
>
> ワークスペースのオーナーのサブスクリプションが終了しています。オーナーが再度購読すると、API キーはすぐにまた使えるようになります。

> [accordion] 403 "API access is not available for this role."
>
> ワークスペースでのあなたの役割は閲覧者です。API を使えるのは、ワークスペースのオーナーと編集者だけです。

## 次のステップ

> [card] [レート制限](https://docs.getqr.com/ja/api/rate-limits.md)

> [card] [認証](https://docs.getqr.com/ja/api/authentication.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.