개념

오류 처리

오류 응답은 상태 코드와 고정된 error 문자열로 구분합니다. 모든 오류 문자열과 재시도 규칙을 정리합니다.

형식

{"error":"invalid request"}

error 값은 고정된 소문자 문자열이라 그대로 비교하면 됩니다. 일부 오류는 필드가 더 있습니다. 429 too many credentials에는 live와 max, 426 plugin_outdated에는 minimum과 downloadUrl, 403 blocked에는 blockedUntil이 붙습니다.

API 응답이 아닌 경우

CDN(Cloudflare)이 요청을 막으면 HTML 본문의 403이 옵니다. 라이브러리 기본 User-Agent(예: Python-urllib)가 그렇습니다. User-Agent에 구현 이름을 넣으면 통과합니다. /api/v1/servers/* 는 이 검사를 받지 않습니다.
허용되지 않은 메서드는 405, 없는 경로는 404입니다. 본문은 {"timestamp","status","error","path"} 형식이라 error 값이 문장입니다.
Content-Type이 application/json이 아니거나 error 값이 아래 목록에 없으면 상태 코드로만 판단하세요.

오류 목록

상태	error	엔드포인트	뜻
400	invalid request	claim, report	필수 필드 누락, 범위 밖의 값, 너무 긴 문자열
400	invalid seed	maps, jobs	시드가 1..2147483647 범위의 정수가 아닙니다
400	invalid cursor	seeds	cursor가 시드 형식이 아닙니다
401	invalid credential	report, revoke	키 없음, 틀린 키, 폐기된 키, 등록된 IP가 아닌 곳에서 보낸 보고
401	invalid code	plugin claim	없는 코드, 만료, 이미 사용, 취소
403	no game server	servers/claim	요청 IP:포트에서 SCP:SL 서버가 응답하지 않습니다
403	private address	servers/claim	사설 또는 루프백 주소에서 보낸 요청
403	claim rejected	plugin claim	수동 확인에서 거절됨
403	blocked	maps, jobs	차단 중인 시드. blockedUntil이 없으면 영구 차단
409	address in use	servers/claim	같은 IP:포트에 사용 중인 등록이 있고 그 키를 보내지 않음
426	plugin_outdated	plugin claim, plugin report	pluginVersion이 최소 버전보다 낮음
429	rate limited	전부	요청 한도 초과
429	too many credentials	servers/claim	이 IP의 사용 중인 키가 이미 최대(live, max)
503	db unavailable	차단 API 전부	데이터베이스 일시 장애
503	disabled	차단 API 전부	운영자가 그 API 를 잠시 껐습니다(feature 필드에 어느 스위치인지). 켜질 때까지 같은 간격으로 다시 시도합니다
503	probe unavailable	servers/claim	서버 확인을 우리 쪽 오류로 못 함
503	(상황에 따라 다름)	maps	{"status":"busy","error":"…"}. 생성 대기열이 가득 찼거나 생성 실패

재시도 규칙

상태	재시도	방법
400, 401, 409, 426	하지 않음	요청, 키, 버전을 고친 뒤 새로 보냅니다
403 no game server, private address	원인을 고친 뒤	발급 간격을 소모하지 않으므로 고치면 바로 다시 보낼 수 있습니다
403 claim rejected	하지 않음	새 코드로 다시 등록합니다
403 blocked	blockedUntil 이후	blockedUntil이 없으면 재시도하지 않습니다
429	예	Retry-After 초 뒤에. 헤더를 안 읽으면 60초부터 2배씩, 최대 10분
503	예	5초 뒤부터, 실패할 때마다 2배, 최대 5분
네트워크 오류, 타임아웃	예	503과 같습니다

429 응답에는 Retry-After 헤더(초)가 있습니다. 그 시간 뒤에 보내면 됩니다. 위 간격은 헤더를 읽지 않는 클라이언트를 위한 권장값입니다.

보고에서 401을 받았을 때

보고를 멈추고 운영자에게 알리세요. 키가 폐기됐거나 서버 IP가 바뀐 것입니다. 직접 등록 키는 같은 IP:포트로 다시 등록하면 새 키가 발급됩니다.

SLMAPS는 SCP: Secret Laboratory의 시드 지도 뷰어입니다. 이 문서는 slmaps.com의 공개 API를 설명합니다.slmaps.com ·