> ## 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 코드가 하나 있는데 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/ko/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/ko/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/ko/api/rate-limits.md)

> [card] [인증](https://docs.getqr.com/ko/api/authentication.md)


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