오류 - GetQR Docs

GetQR API는 베타 버전이며 일부 워크스페이스에서만 사용할 수 있습니다. 정식 출시 전에 세부 사항이 변경될 수 있습니다.

GetQR API는 표준 HTTP 상태 코드를 사용합니다. 성공한 요청은 2xx를 반환합니다. 실패한 요청은 4xx 또는 5xx와 함께 무엇이 잘못되었는지 설명하는 JSON 본문을 반환합니다.

오류 형식

모든 오류는 같은 구조를 가집니다. 고정된 코드, 사람이 읽을 수 있는 메시지, 해당 코드 설명으로 연결되는 링크입니다.

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

string

필수

고정된, 기계가 읽을 수 있는 오류 코드입니다. 코드에서는 메시지 대신 이 값을 사용하세요. 오류 코드를 참조하세요.

string

필수

사람이 읽을 수 있는 문제 설명입니다. 문구는 바뀔 수 있습니다.

string

필수

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 키가 현재 윈도의 요청 수를 모두 사용했습니다. 요청 한도를 참조하세요.
`internal_server_error`	500	GetQR 측에서 문제가 발생했습니다. 나중에 다시 시도하고, 문제가 계속되면 지원팀에 문의하세요.

유효성 검사 오류

본문이나 쿼리 매개변수가 유효성 검사를 통과하지 못하면 API는 422를 반환합니다. 메시지는 첫 번째로 잘못된 필드를 <issue>: <field>: <details> 형식으로 설명합니다.

{
  "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 헤더의 초만큼 기다리세요. 한도를 초과한 경우를 참조하세요.
5xx 오류는 지수 백오프로 재시도하세요.

자주 발생하는 문제

모든 요청이 404 "This endpoint is not available."를 반환합니다

API는 베타 버전이며 아직 워크스페이스에서 활성화되지 않았습니다.

404 "This endpoint does not exist."

경로가 잘못되었습니다. 엔드포인트 페이지와 대조하고, 경로가 /api/v1/로 시작하는지 확인하세요.

403 "Access denied: This account does not have an active subscription."

워크스페이스 소유자의 구독이 종료되었습니다. 소유자가 다시 구독하면 API 키는 바로 다시 작동합니다.

403 "API access is not available for this role."

워크스페이스에서의 역할이 뷰어입니다. API는 워크스페이스 소유자와 편집자만 사용할 수 있습니다.

API

오류

오류 형식

오류 코드

유효성 검사 오류

오류 처리

자주 발생하는 문제

다음 단계

요청 한도

인증

​오류 형식

​오류 코드

​유효성 검사 오류

​오류 처리

​자주 발생하는 문제

​다음 단계

요청 한도

인증

오류 형식

오류 코드

유효성 검사 오류

오류 처리

자주 발생하는 문제

다음 단계