오류 코드

요청이 실패하면 응답의 오류 코드를 확인하세요. 아래 목록에서 해당 코드를 펼치면 원인과 해결 방법을 확인할 수 있습니다. 각 오류에는 응답 예시와 재시도 안내도 있습니다.

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

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

응답

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

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

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

응답

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

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

해결 방법: 토큰을 발급하거나 취소할 때는 Authorization 헤더에 ApiKey와 API 키를 사용하세요. 다른 요청에는 Bearer와 액세스 토큰을 사용하세요.
재시도 정책: 올바른 헤더를 제공한 뒤 재시도하세요.

응답

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

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

해결 방법: 연동 앱이 어느 IP 주소에서 API에 연결하는지 확인하세요. 오류가 계속되면 Shopently 기술 지원에 문의하세요.
재시도 정책: IP 주소 식별 문제가 해결된 후 다시 시도하세요.

응답

{
  "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 목록 편집을 요청하세요.
재시도 정책: 주소가 허용된 뒤에만 재시도하세요.

응답

{
  "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키에 이 작업에 필요한 유효한 권한이 없습니다.

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

응답

{
  "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 접근이 활성화될 때까지 재시도하지 마세요.

응답

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

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

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

응답

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

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

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

응답

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

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

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

응답

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

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

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

응답

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

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

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

응답

{
  "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이 멱등성 키는 다른 요청에 속합니다.

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

응답

{
  "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고유 값이 기존 리소스와 충돌합니다.

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

응답

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

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

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

응답

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

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

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

응답

{
  "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 을 제출하세요.
재시도 정책: 조정한 작업에는 새 멱등성 키를 사용하고 무조건 덮어쓰지 마세요.

응답

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

409storage.limit_reached이미지와 파일 저장 용량이 한도에 도달했습니다. 공간을 확보하거나 한도를 늘리세요.

해결 방법: 이미지와 파일 저장 용량이 한도에 도달했습니다. 공간을 확보하거나 한도를 늘리세요.
재시도 정책: 작고 유효한 작업에 각각의 멱등성 키를 사용해 재시도하세요.

응답

{
  "error": {
    "code": "storage.limit_reached",
    "fields": null,
    "message": "The upload storage limit is reached."
  },
  "meta": {
    "request_id": "example-request"
  }
}

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

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

응답

{
  "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 과 지원되는 비압축 본문을 사용하세요.
재시도 정책: 미디어 유형이나 인코딩을 수정한 뒤 재시도하세요.

응답

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

416request.range_not_satisfiable제약 조건: Range

해결 방법: Range: bytes=0-(size_bytes-1)
재시도 정책: 요청을 수정한 뒤 재시도하세요.

응답

{
  "error": {
    "code": "request.range_not_satisfiable",
    "fields": null,
    "message": "The requested byte range is unavailable."
  },
  "meta": {
    "request_id": "example-request"
  }
}

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

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

응답

{
  "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에 지정된 초 이상 기다리세요. 쓰기를 재시도한다면 요청 본문과 Idempotency-Key 값을 그대로 유지하세요.

응답

{
  "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에 지정된 초 이상 기다리세요. 쓰기를 재시도한다면 요청 본문과 Idempotency-Key 값을 그대로 유지하세요.

응답

{
  "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에 지정된 초 이상 기다리세요. 쓰기를 재시도한다면 요청 본문과 Idempotency-Key 값을 그대로 유지하세요.

응답

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

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

해결 방법: 잠시 기다린 뒤 요청을 다시 보내세요. 오류 500이 다시 발생하면 요청 ID를 포함해 Shopently 기술 지원에 문의하세요.
재시도 정책: 데이터 읽기는 잠시 기다린 뒤 다시 시도할 수 있습니다. 쓰기를 재시도할 때는 같은 Idempotency-Key 값을 사용하고 요청 본문을 변경하지 마세요.

응답

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

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

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

응답

{
  "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 헤더가 있으면 지정된 초만큼 기다린 뒤 다시 시도하세요. 헤더가 없으면 잠시 기다리세요. 오류가 계속되면 요청 ID를 포함해 Shopently 기술 지원에 문의하세요.
재시도 정책: 위에서 설명한 대기 시간을 지킨 후 다시 시도하세요. 쓰기를 재시도할 때는 같은 Idempotency-Key 값을 사용하고 요청 본문을 변경하지 마세요.

응답

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

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

해결 방법: 데이터를 변경하는 요청이었다면 변경 사항이 스토어에 저장되었는지 확인하세요. 응답이 없다고 해서 저장이 실패한 것은 아닙니다. 오류가 계속되면 요청 ID를 포함해 Shopently 기술 지원에 문의하세요.
재시도 정책: 데이터 읽기는 잠시 기다린 뒤 다시 시도할 수 있습니다. 쓰기를 재시도할 때는 같은 Idempotency-Key 값을 사용하고 요청 본문을 변경하지 마세요.

응답

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