오류와 복구

안정적인 오류 코드를 기준으로 수정, 대기, 재시도 여부를 결정합니다.

해결 방법

사람이 읽는 error.message 대신 HTTP 상태와 error.code 로 분기하세요.
401 은 유효한 인증이 필요하고, 403 은 접근 권한이나 요금제를 변경해야 하며, 409 는 충돌한 작업이나 리소스 버전을 확인해야 합니다.

접근 거부 및 재시도

401: 401이 항상 토큰 만료를 뜻하지는 않습니다. 만료되었다면 새 토큰을 받고 읽기 요청을 최대 한 번만 재시도하세요. 토큰 발급이 401을 반환하면 키를 확인하고 자동 시도를 중지하세요.
403: 403이면 권한, IP 제한 및 요금제를 확인하세요. 새 토큰을 받아도 취소된 접근 권한이 복구되지는 않습니다.

인증

재시도 정책

일시적 오류에는 재시도 횟수를 제한하고 대기 시간을 늘리며 무작위 지연을 추가하세요.
Retry-After 가 있으면 준수하세요.
쓰기 시간이 초과되면 결과를 알 수 없을 수 있습니다.
같은 논리 작업을 재시도할 때는 원래 Idempotency-Key 와 변경하지 않은 요청을 유지하세요.
아래 목록은 공개된 모든 오류 코드를 설명합니다.

안전한 쓰기

요청 속도 제한

422 / 409

가격의 통화 형식이나 금액의 정밀도가 유효하지 않으면 422 request.validation_failed가 반환됩니다.
유효한 통화 코드라도 선택한 가격표의 통화와 다르면 409 resource.version_conflict가 반환됩니다.
재시도 전에 컨텍스트와 버전을 확인하세요.

오류 목록

400request.malformed요청을 파싱할 수 없습니다.

해결 방법: JSON 구문, URL 인코딩, 요청 구조를 확인하세요.
재시도 정책: 요청을 수정한 뒤 재시도하세요.

JSON

{
  "error": {
    "code": "request.malformed",
    "fields": null,
    "message": "The request could not be read."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.invalid_credentialsAPI 키 또는 액세스 토큰이 잘못되었거나 만료 또는 폐기되었습니다.

해결 방법: 스토어 URL과 인증 정보를 확인하세요. 활성 API 키로 새 토큰을 발급받으세요.
재시도 정책: 인증을 수정한 뒤 재시도하세요. 잘못된 토큰 요청을 반복하지 마세요.

JSON

{
  "error": {
    "code": "authentication.invalid_credentials",
    "fields": null,
    "message": "The credentials are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.required필수 Authorization 헤더가 없거나 인증 방식이 잘못되었습니다.

해결 방법: 토큰 요청에는 ApiKey, 리소스 작업에는 Bearer 를 사용하세요.
재시도 정책: 올바른 헤더를 제공한 뒤 재시도하세요.

JSON

{
  "error": {
    "code": "authentication.required",
    "fields": null,
    "message": "Authentication is required."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.client_ip_unverified서비스에서 신뢰할 수 있는 클라이언트 IP 주소를 확인하지 못했습니다.

해결 방법: 스토어 운영자에게 수신 경로 점검을 요청하세요. 전달 헤더를 직접 삽입하지 마세요.
재시도 정책: 신뢰할 수 있는 연결 경로가 복구된 뒤 재시도하세요.

JSON

{
  "error": {
    "code": "authorization.client_ip_unverified",
    "fields": null,
    "message": "The client IP address could not be verified."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.ip_not_allowed출발지 IP 주소가 키의 허용 주소 목록에 없습니다.

해결 방법: 허용된 출발지 주소를 사용하거나 권한이 있는 관리자에게 키 IP 목록 편집을 요청하세요.
재시도 정책: 주소가 허용된 뒤에만 재시도하세요.

JSON

{
  "error": {
    "code": "authorization.ip_not_allowed",
    "fields": null,
    "message": "Access from this IP address is not allowed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.scope_denied키에 이 작업에 필요한 유효한 권한이 없습니다.

해결 방법: 작업의 필수·조건부 권한, 키에 부여된 권한, 발급자의 접근 권한을 확인하세요.
재시도 정책: 권한이 있는 관리자가 필요한 접근 권한을 부여한 뒤 재시도하세요.

JSON

{
  "error": {
    "code": "authorization.scope_denied",
    "fields": null,
    "message": "The required permission has not been granted."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.api_disabled이 스토어의 API 접근이 비활성화되었습니다.

해결 방법: 스토어 소유자에게 활성 요금제와 API 사용 가능 여부를 확인해 달라고 요청하세요.
재시도 정책: API 접근이 활성화될 때까지 재시도하지 마세요.

JSON

{
  "error": {
    "code": "entitlements.api_disabled",
    "fields": null,
    "message": "API access is disabled for this store."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.limit_exceeded변경하면 현재 요금제의 한도를 초과합니다.

해결 방법: 적용되는 리소스 한도를 확인하고 변경 내용이나 요금제를 조정하세요.
재시도 정책: 한도 문제를 해결한 뒤 재시도하세요. 요청이 바뀌면 새 멱등성 키를 사용하세요.

JSON

{
  "error": {
    "code": "entitlements.limit_exceeded",
    "fields": null,
    "message": "The operation exceeds a plan limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.operation_disabled현재 요금제에는 이 작업이 포함되어 있지 않습니다.

해결 방법: 작업에 표시된 최소 요금제를 확인하세요.
재시도 정책: 요금제에서 작업을 허용하고 키에 필요한 권한이 있을 때 재시도하세요.

JSON

{
  "error": {
    "code": "entitlements.operation_disabled",
    "fields": null,
    "message": "The current plan does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.resource_blocked요금제 한도가 이 리소스를 차단하고 있습니다.

해결 방법: 소유자에게 리소스의 요금제 제한 해결을 요청하세요.
재시도 정책: 리소스가 차단된 동안 같은 요청을 반복하지 마세요.

JSON

{
  "error": {
    "code": "entitlements.resource_blocked",
    "fields": null,
    "message": "A plan limit blocks access to this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

404resource.not_found리소스가 없거나 삭제되었거나 제공한 식별자로 접근할 수 없습니다.

해결 방법: 스토어, 리소스 경로, 식별자를 확인하세요. 이 스토어가 반환한 식별자를 사용하세요.
재시도 정책: 대상을 수정하거나 존재 여부를 확인한 뒤에만 재시도하세요.

JSON

{
  "error": {
    "code": "resource.not_found",
    "fields": null,
    "message": "The resource was not found."
  },
  "meta": {
    "request_id": "example-request"
  }
}

405request.method_not_allowed엔드포인트에서 이 HTTP 메서드를 지원하지 않습니다.

해결 방법: 문서에 명시된 메서드를 사용하세요. Allow 헤더가 지원하는 메서드를 알려줍니다.
재시도 정책: 지원하지 않는 메서드를 재시도하지 마세요.

JSON

{
  "error": {
    "code": "request.method_not_allowed",
    "fields": null,
    "message": "This method is not supported for this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409idempotency.key_reused이 멱등성 키는 다른 요청에 속합니다.

해결 방법: 원래 작업을 찾으세요. 의도적으로 새로운 논리 작업을 할 때만 새 키를 사용하세요.
재시도 정책: 충돌하는 키로 변경된 내용을 재시도하지 마세요.

JSON

{
  "error": {
    "code": "idempotency.key_reused",
    "fields": null,
    "message": "This idempotency key was used with a different request."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.already_exists고유 값이 기존 리소스와 충돌합니다.

해결 방법: 기존 리소스를 읽고 이를 사용할지 다른 고유 값을 선택할지 결정하세요.
재시도 정책: 같은 충돌하는 생성 작업을 반복하지 마세요.

JSON

{
  "error": {
    "code": "resource.already_exists",
    "fields": null,
    "message": "A resource with these unique values already exists."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.in_use다른 리소스가 아직 이 리소스에 의존합니다.

해결 방법: 의존 관계를 검토하고 삭제 전에 지원되는 작업으로 제거하거나 변경하세요.
재시도 정책: 의존 관계를 해결한 뒤 재시도하세요.

JSON

{
  "error": {
    "code": "resource.in_use",
    "fields": null,
    "message": "The resource is still in use."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.state_conflict현재 업무 상태에서 이 변경을 허용하지 않습니다.

해결 방법: 현재 상태를 읽고 유효한 업무 상태 전환을 선택하세요.
재시도 정책: 충돌하는 변경을 자동으로 강제하거나 반복 제출하지 마세요.

JSON

{
  "error": {
    "code": "resource.state_conflict",
    "fields": null,
    "message": "The current resource state does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.version_conflict읽은 버전 이후 다른 쓰기가 리소스를 변경했습니다.

해결 방법: 최신 상태를 읽고 변경 사항을 조정한 뒤 새 expected_version 을 제출하세요.
재시도 정책: 조정한 작업에는 새 멱등성 키를 사용하고 무조건 덮어쓰지 마세요.

JSON

{
  "error": {
    "code": "resource.version_conflict",
    "fields": null,
    "message": "The resource version has changed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

413request.too_large요청이 크기 제한을 초과했습니다.

해결 방법: 내용을 줄이거나 지원되는 개별 작업으로 나누세요.
재시도 정책: 작고 유효한 작업에 각각의 멱등성 키를 사용해 재시도하세요.

JSON

{
  "error": {
    "code": "request.too_large",
    "fields": null,
    "message": "The request exceeds the size limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

415request.unsupported_media_type미디어 유형 또는 콘텐츠 인코딩을 지원하지 않습니다.

해결 방법: JSON 쓰기에는 Content-Type: application/json 과 지원되는 비압축 본문을 사용하세요.
재시도 정책: 미디어 유형이나 인코딩을 수정한 뒤 재시도하세요.

JSON

{
  "error": {
    "code": "request.unsupported_media_type",
    "fields": null,
    "message": "The request media type or encoding is not supported."
  },
  "meta": {
    "request_id": "example-request"
  }
}

422request.validation_failed하나 이상의 필드 또는 매개변수가 검증을 통과하지 못했습니다.

해결 방법: error.fields 를 확인한 다음 필수 필드, null 허용 여부, 식별자, 허용 값을 점검하세요.
재시도 정책: 수정한 요청을 재시도하세요. 변경된 쓰기는 새로운 논리 작업입니다.

JSON

{
  "error": {
    "code": "request.validation_failed",
    "fields": null,
    "message": "Some request parameters are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.queue_fullAPI의 짧은 대기열이 가득 찼습니다. 요청 실행은 시작되지 않았습니다.

해결 방법: 요청을 대기열에 넣고 Retry-After 응답 헤더를 준수하세요.
재시도 정책: 최소 Retry-After 초를 기다리고 무작위 지연을 추가하세요. 쓰기 재시도 시 원래 키와 내용을 유지하세요.

JSON

{
  "error": {
    "code": "capacity.queue_full",
    "fields": null,
    "message": "The API is busy. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.wait_timeoutAPI 대기열의 대기 시간이 초과되었습니다. 요청 실행은 시작되지 않았습니다.

해결 방법: 요청을 대기열에 넣고 Retry-After 응답 헤더를 준수하세요.
재시도 정책: 최소 Retry-After 초를 기다리고 무작위 지연을 추가하세요. 쓰기 재시도 시 원래 키와 내용을 유지하세요.

JSON

{
  "error": {
    "code": "capacity.wait_timeout",
    "fields": null,
    "message": "The API could not start this request in time. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429rate_limit.exceeded요청 속도가 적용 한도를 초과했습니다.

해결 방법: 요청을 대기열에 넣고 Retry-After 응답 헤더를 준수하세요.
재시도 정책: 최소 Retry-After 초를 기다리고 무작위 지연을 추가하세요. 쓰기 재시도 시 원래 키와 내용을 유지하세요.

JSON

{
  "error": {
    "code": "rate_limit.exceeded",
    "fields": null,
    "message": "The request rate limit has been exceeded."
  },
  "meta": {
    "request_id": "example-request"
  }
}

500internal.error예상하지 못한 서비스 오류가 발생했습니다.

해결 방법: 요청 식별자를 기록하고 오류가 지속되면 운영자에게 연락하세요. 로그에 인증 정보를 넣지 마세요.
재시도 정책: 횟수를 제한한 백오프를 사용하세요. 쓰기는 원래 멱등성 키와 변경하지 않은 내용을 유지하세요.

JSON

{
  "error": {
    "code": "internal.error",
    "fields": null,
    "message": "An unexpected error occurred."
  },
  "meta": {
    "request_id": "example-request"
  }
}

502gateway.bad_response게이트웨이가 유효한 API 응답을 받지 못했습니다.

해결 방법: 요청 식별자를 보관하세요. 응답 실패가 쓰기가 적용되지 않았음을 의미하지는 않습니다.
재시도 정책: 횟수를 제한한 백오프를 사용하세요. 같은 논리적 쓰기는 원래 Idempotency-Key 와 내용으로 반복하세요.

JSON

{
  "error": {
    "code": "gateway.bad_response",
    "fields": null,
    "message": "The API gateway could not obtain a valid response."
  },
  "meta": {
    "request_id": "example-request"
  }
}

503service.unavailableAPI가 일시적으로 요청을 처리할 수 없습니다.

해결 방법: Retry-After 가 있으면 준수하고 장애가 지속되면 요청 식별자를 보관하세요.
재시도 정책: 횟수를 제한하고 무작위 지연을 더한 백오프를 사용하세요. 같은 쓰기를 재시도할 때는 키와 내용을 유지하세요.

JSON

{
  "error": {
    "code": "service.unavailable",
    "fields": null,
    "message": "The API is temporarily unavailable."
  },
  "meta": {
    "request_id": "example-request"
  }
}

504gateway.timeout게이트웨이가 API 응답을 기다리다 시간 초과되었습니다.

해결 방법: 요청 식별자를 보관하고 쓰기 결과는 알 수 없는 상태로 취급하세요.
재시도 정책: 횟수를 제한한 백오프를 사용하세요. 쓰기에는 원래 멱등성 키와 변경하지 않은 내용을 재사용하세요.

JSON

{
  "error": {
    "code": "gateway.timeout",
    "fields": null,
    "message": "The API gateway timed out."
  },
  "meta": {
    "request_id": "example-request"
  }
}