오류와 응답 형식

응답 봉투, 오류 형식, 상태 코드, 캐시 헤더를 설명합니다.

이 문서의 목차 (5)

01성공 응답
02오류 응답
03상태 코드
04캐시
05페이지네이션

성공 응답#

성공한 응답은 항상 data 로 감싸여 옵니다. 부가 정보가 있으면 meta 가 함께 옵니다.

{
  "data": { "…": "실제 내용" },
  "meta": { "next_cursor": null }
}

참고

data 로 감싸는 이유는 나중에 meta 를 붙이더라도 여러분 코드가 깨지지 않게 하기 위해서입니다.
최상위에 배열을 바로 두면 필드를 하나도 추가할 수 없습니다.

오류 응답#

오류는 전부 RFC 9457 형식입니다.
Content-Type 은 application/problem+json 입니다.

{
  "type": "https://api.mcmi.kr/problems/rate-limited",
  "title": "요청 한도를 넘었습니다",
  "status": 429,
  "detail": "분당 5회를 넘겼습니다. 상향이 필요한 경우 신청해주세요.",
  "retry_after": 42
}

필드	뜻
`type`	오류 종류를 가리키는 URI. 분기 조건으로 쓰기에 가장 안전합니다
`title`	사람이 읽는 짧은 제목
`status`	HTTP 상태 코드와 같은 값
`detail`	이번 경우에 한정된 설명
`retry_after`	(`429` 일 때만) 몇 초 뒤에 다시 오시면 되는지. `Retry-After` 헤더와 같은 값

도움말

title 이나 detail 문구는 다듬어질 수 있습니다. 조건 분기는 type 이나 status 로 해주세요.

상태 코드#

코드	`type`	언제
`400`	`bad-request`	좌표·월드 이름·`type`·`cursor` 값이 올바르지 않거나, 닉네임 형식이 아닐 때
`401`	`unauthorized`	키가 없거나, 폐기된 키일 때
`404`	`not-found`	그런 플레이어·문서·엔드포인트가 없을 때
`429`	`rate-limited`	한도를 넘었을 때. `Retry-After` 를 보고 기다려 주세요
`503`	`service-unavailable`	게임 서버 브릿지가 응답하지 않을 때
`500`	`internal-error`	서버 내부 오류. 잠시 후 다시 시도해 주세요

중요

503 은 일시적인 상태입니다. 지리·유저 상점처럼 게임 서버 안에서 직접 답해야 하는 엔드포인트는 브릿지가 준비되지 않으면 503 을 돌려드립니다.
빈 배열이나 null 로 얼버무리지 않습니다 — "없다"와 "지금 못 본다"는 다른 뜻이기 때문입니다.

캐시#

엔드포인트	캐시
`/v1/status`	10초
`/v1/docs`, `/v1/docs/{경로}`	5분
`/v1/economy/currencies`	1시간
`/v1/players/…`	30초 (개인 캐시)
`/v1/location/resolve`	1분
`/v1/shops/user/…`	1분 (개인 캐시)
`/v1/openapi.json`	5분

Cache-Control 을 존중해 주시면 한도를 훨씬 여유 있게 쓰실 수 있습니다.
같은 값을 매초 다시 물으시면 한도만 소모되고 응답은 똑같습니다.

페이지네이션#

목록이 긴 엔드포인트는 커서 방식입니다.

curl -H "Authorization: Bearer ml_…" \
     "https://api.mcmi.kr/v1/players/rihacats/killlog?limit=50"

응답 meta.next_cursor 에 값이 있으면 다음 장이 있다는 뜻입니다.

{ "meta": { "next_cursor": "128" } }

그 값을 cursor 로 넘기시면 이어서 받으실 수 있습니다. null 이면 끝입니다.

API 개요 · 인증과 한도

댓글은 마코노미 디스코드 서버 멤버만 쓸 수 있어요. 디스코드로 로그인