# 에러 코드 레퍼런스

## HTTP 상태 코드

| 코드 | 의미 | 원인 | 해결 방법 |
|------|------|------|----------|
| 400 | Bad Request | 요청 파라미터가 잘못됨, **또는 앱에 필요한 스코프가 없음** | 필수 필드 확인, 타입/형식 검증. `Insufficient scope` 메시지라면 아래 [스코프 관련 에러](#스코프-관련-에러) 참조 |
| 401 | Unauthorized | API Key가 없거나, 유효하지 않거나, **비활성 상태이거나, 앱이 삭제됨** | 앱 상세에서 API Key 가 **활성**인지 먼저 확인. 그래도 안 되면 재발급 |
| 403 | Forbidden | 해당 리소스에 접근 권한 없음 | OAuth 스코프 확인 또는 팀 권한 확인 |
| 404 | Not Found | 리소스(워크스페이스, 상품 등)가 존재하지 않음 | ID 값 재확인 |
| 409 | Conflict | 중복 요청 또는 상태 충돌 | 현재 상태 확인 후 재시도 |
| 422 | Unprocessable Entity | 요청은 유효하나 처리 불가 | 비즈니스 로직 조건 확인 (예: 크레딧 부족) |
| 429 | Too Many Requests | 요청 속도 제한 초과 | 잠시 대기 후 재시도 |
| 500 | Internal Server Error | 서버 내부 오류 | 잠시 후 재시도, 지속 시 지원팀 문의 |

## 스코프 관련 에러

새로 만든 앱에서 가장 먼저 마주치는 실패입니다. **앱은 스코프가 하나도 없는 상태로 생성되므로**, 키를 제대로 발급·활성화했어도 권한을 저장하기 전에는 모든 호출이 실패합니다.

```json
{
  "status": 400,
  "error": { "code": "INTERNAL-009", "message": "Insufficient scope. Required: user:read" },
  "data": null
}
```

| 증상 | 원인 | 해결 |
|------|------|------|
| `400` + `Insufficient scope. Required: <스코프>` | 앱에 그 스코프가 저장돼 있지 않음 | 개발자 포털 **앱 → 권한 관리**에서 `Required:` 가 가리키는 스코프를 추가하고 저장 ([자격증명 발급 가이드](credentials.md) 4단계) |
| 키를 재발급해도 같은 `400` 이 계속됨 | 스코프 문제는 키와 무관함 | 재발급 대신 권한 설정을 확인 |

> 권한을 저장한 뒤에는 키를 다시 발급하지 않아도 곧바로 반영됩니다.

## 상품 상태 변경 에러

| 현재 상태 | 허용되는 변경 | 불가능한 변경 |
|----------|-------------|-------------|
| 생성 중 | 변경 불가 (생성 완료 대기) | 모든 상태 변경 |
| BEFORE_REVIEW | IN_REVIEW | REVIEW_COMPLETE (단계 건너뛰기 불가) |
| IN_REVIEW | REVIEW_COMPLETE, BEFORE_REVIEW | - |
| REVIEW_COMPLETE | BEFORE_REVIEW, IN_REVIEW | - |

## 이미지 업로드 에러

| 상황 | 원인 | 해결 |
|------|------|------|
| Presigned URL 만료 | URL 발급 후 1시간 초과 | `POST /openapi/v1/images/upload-url` (MCP: `get_upload_url`) 로 새 URL 발급 |
| PUT 업로드 403 | URL 서명 불일치 | 새 Presigned URL 발급 후 재시도 |
| 파일 형식 오류 | 지원하지 않는 확장자 | jpg, jpeg, png, gif, webp, heic 중 사용 |

## 크레딧 관련 에러

| 상황 | 해결 |
|------|------|
| 크레딧 부족으로 상품 생성 실패 | `GET /openapi/v1/usage/credits` (MCP: `get_credits`) 로 잔액 확인 → 충전 후 재시도 |
| 상품 생성 후 크레딧 미차감 | 비동기 처리 중일 수 있음. 잠시 후 재확인 |