마인플랫폼 문서

테마

오류·상태 코드 ​

모든 오류 응답은 JSON이며, 최소 error 문자열 필드를 포함해요.

json
{
  "error": "사람이 읽을 수 있는 메시지"
}

일부 경우에는 추가 필드가 붙어요. (예: rate limit의 limit)

HTTP 상태 코드 ​

코드의미대표 상황
200성공목록 조회·헬스 정상
204No ContentOPTIONS CORS preflight 성공
401Unauthorized키 없음·형식 오류·폐기·불일치
404Not Found알 수 없는 경로·메서드 조합
429Too Many Requests키당 1 RPS 초과
502Bad Gateway업스트림(인증·DB) 일시 오류
503Service UnavailableAPI 서버 설정 미완

오류 본문 예시 ​

401 — 키 문제 ​

json
{
  "error": "Invalid or missing API key."
}

확인할 것:

  • Authorization: Bearer mp_live_… 형식인가?
  • 키가 잘렸거나 앞뒤 공백이 섞이지 않았는가?
  • 대시보드에서 삭제(폐기)한 키인가?
  • 다른 계정의 키를 쓰고 있지 않은가?

429 — 한도 초과 ​

json
{
  "error": "Rate limit exceeded",
  "limit": "1 rps"
}

헤더: Retry-After: 1
→ 요청 한도

404 — 경로 없음 ​

json
{
  "error": "Not found."
}

예: POST /v1/servers, GET /v1/unknown

502 — 업스트림 실패 ​

json
{
  "error": "Authentication service error."
}

또는

json
{
  "error": "Failed to load servers."
}

일시적일 수 있어요. 잠시 후 재시도하고, 지속되면 고객센터에 시각·요청 경로를 알려 주세요.

503 — 서버 미설정 ​

json
{
  "error": "API server is not configured."
}

운영 측 환경 변수 문제일 때 나타나요. 사용자 키 문제가 아닙니다.

성공 응답과 Content-Type ​

성공·실패 모두 기본적으로:

http
Content-Type: application/json; charset=utf-8

CORS 관련 헤더도 함께 내려가요.

http
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Max-Age: 86400

메서드 ​

현재 GET (및 CORS용 OPTIONS)만 지원해요.
POST/PUT/PATCH/DELETE 로 데이터 API를 호출하면 404 또는 허용되지 않은 메서드로 실패해요.

디버깅 체크리스트 ​

  1. GET https://api.mineplatform.kr/health → { "ok": true, ... } 인가?
  2. 같은 환경에서 Bearer 키로 /v1/servers를 치는가?
  3. 1초 안에 중복 호출하지 않는가?
  4. 응답 본문 error 문자열을 로그에 남겼는가?
  5. Retry-After 를 지켰는가?