오류 코드(Error Codes)

이 페이지에서는 Ruby API에서 반환하는 정확한 오류 응답을 문서화합니다.

응답 형태

API는 오류 유형에 따라 두 가지 서로 다른 응답 형태를 사용합니다.

비즈니스 오류 (401 / 404 / 409)

detail 필드는 문자열입니다.

{
  "detail": "<error message>"
}

유효성 검증 오류 (422)

detail 필드는 각 유효성 검증 실패를 설명하는 객체의 배열입니다.

{
  "detail": [
    {
      "loc": ["body", "field_name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

---

401 — 인증 실패

모든 인증 실패는 HTTP 401을 반환합니다. detail 값은 서버에서 반환하는 정확한 문자열 중 하나입니다.

detail 값	의미	해결 방법
无效的 API Key	시스템에서 API 키를 찾을 수 없음	X-Team-Key 헤더 값을 확인하십시오
无效的时间戳格式	타임스탬프가 유효한 정수가 아님	X-Team-Timestamp를 Unix epoch 정수로 전송하십시오 (예: 1712345678)
请求时间戳超出允许范围（±300秒）	타임스탬프가 ±300초 범위를 초과함	시스템 시계를 동기화하고, 요청이 즉시 전송되도록 하십시오
签名验证失败	HMAC-SHA256 서명이 일치하지 않음	서명 알고리즘과 문자열 구성을 다시 확인하십시오
Team 已禁用	팀 계정이 비활성화됨	팀 계정을 다시 활성화하려면 지원팀에 문의하십시오

---

404 — 리소스를 찾을 수 없음

요청한 리소스가 존재하지 않거나 인증된 팀에 속하지 않는 경우 HTTP 404가 반환됩니다.

엔드포인트	detail 값	조건
GET /api/player/{id}	玩家不存在	플레이어 ID를 찾을 수 없음
GET /api/bet/{id}	注单不存在	베팅 기록 ID를 찾을 수 없음
GET /api/sports-bet/{id}	体育注单不存在	스포츠 베팅 기록 ID를 찾을 수 없음
PUT /api/provider-limit/team/{provider_id}	游戏商不存在	프로바이더(Provider) ID를 찾을 수 없음
GET /api/provider-limit/brand/{brand_id}	品牌不存在	브랜드 ID를 찾을 수 없거나 팀 소유가 아님
PUT /api/provider-limit/brand/{brand_id}/{provider_id}	品牌不存在	브랜드 ID를 찾을 수 없거나 팀 소유가 아님
PUT /api/provider-limit/brand/{brand_id}/{provider_id}	游戏商不存在	프로바이더(Provider) ID를 찾을 수 없음

---

409 — 충돌

고유성 제약 조건이 위반된 경우 HTTP 409가 반환됩니다.

엔드포인트	detail 값	조건
POST /api/brand/create	品牌代码 '{code}' 已存在	해당 팀에 동일한 code를 가진 브랜드가 이미 존재합니다. {code}는 실제 제출된 값으로 대체됩니다.

---

422 — 유효성 검증 오류

요청 본문 또는 쿼리 파라미터가 스키마 유효성 검증에 실패하면 FastAPI가 HTTP 422를 반환합니다. detail 필드는 배열이며, 각 요소는 하나의 유효하지 않은 필드를 설명합니다.

예시 — 필수 필드 누락:

{
  "detail": [
    {
      "loc": ["body", "code"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

예시 — 복수 유효성 검증 실패:

{
  "detail": [
    {
      "loc": ["body", "min_bet"],
      "msg": "value is not a valid decimal",
      "type": "type_error.decimal"
    },
    {
      "loc": ["query", "page"],
      "msg": "ensure this value is greater than or equal to 1",
      "type": "value_error.number.not_ge"
    }
  ]
}

---

향후 개선 사항

구조화된 영문 오류 코드(예: INVALID_API_KEY, PLAYER_NOT_FOUND)가 향후 릴리스에 추가될 예정입니다. 현재 API는 중국어 detail 문자열을 반환합니다.