오류
javinfo API가 반환하는 HTTP 상태 코드와 오류 본문.
실패한 요청은 청구되지 않습니다. 비용은 200에만 붙습니다.
상태 코드
| 상태 | 의미 |
|---|---|
400 | 잘못된 요청. 입력 검증 실패(매개변수 누락, 범위 초과, 잘못된 enum), /query나 /idols에 q도 필터도 없음, 제공업체 id 불명. |
401 | API 키가 없거나 유효하지 않음. |
402 | 크레딧 부족. Retry-After는 한 시간, 자동화 클라이언트용 힌트이며 충전하면 즉시 풀립니다. 요금 참조. |
404 | 결과 없음. /movie, /random, /idols/{id}, /discover/similar, /analytics/idols/* 조회, /resolve, /resolve/provenance, /resolve/streams가 반환. |
422 | /query 전용: 해당 필터/정렬을 지원하는 제공업체가 없거나, 고정한 곳이 미지원이거나, q 없이 50페이지를 넘김. 필터링 참조. |
429 | 요청 과다: 계정의 분당 상한 또는 실시간 제공업체의 시간당 예산. Retry-After만큼 대기. |
503 | providers=로 고정한 제공업체가 시간당 예산 초과. 고정을 풀거나 Retry-After만큼 대기. |
499 | 제공업체 응답 전에 클라이언트가 요청을 닫음. |
/query는 404를 반환하지 않습니다. 일치 없음은 count: 0과 빈 results 배열을 가진
200이고 무료 — count를 보세요. 이름 조회(/idols/{id}, /discover/similar,
resolve)는 코드나 출연자가 없으면 404를 반환합니다.
오류 본문
핸들러 오류는 oRPC 봉투를 쓰며 defined, code, status, message를 담습니다:
{
"defined": false,
"code": "NOT_FOUND",
"status": 404,
"message": "no title found for \"ZZZZ-99999\""
}400은 실패한 규칙마다 data.issues를 하나씩 더합니다:
{
"defined": false,
"code": "BAD_REQUEST",
"status": 400,
"message": "Input validation failed",
"data": {
"issues": [
{
"expected": "string",
"code": "invalid_type",
"path": ["q"],
"message": "Invalid input: expected string, received undefined"
}
]
}
}422: 같은 봉투에 status: 422, code: "BAD_REQUEST":
{
"defined": false,
"code": "BAD_REQUEST",
"status": 422,
"message": "does not support sort \"rating\""
}게이트 거부는 핸들러 전이라 더 짧습니다:
{ "error": "invalid api key" }키가 아예 없으면 게이트를 통과하고 핸들러가 oRPC UNAUTHORIZED 본문으로 거부합니다:
{
"defined": false,
"code": "UNAUTHORIZED",
"status": 401,
"message": "Unauthorized"
}분당 제한기도 짧은 형식을 씁니다: { "error": "rate limit exceeded" }.
code가 항상 있다고 가정하지 말고 상태 코드로 분기한 뒤 본문을 읽으세요.
백오프
429, 402, 503은 초 단위 Retry-After를 함께 보냅니다. 지키세요:
if ([429, 402, 503].includes(res.status)) {
const wait = Number(res.headers.get('Retry-After') ?? 1);
await new Promise((r) => setTimeout(r, wait * 1000));
}402의 한 시간은 권고입니다. 사람이 보고 있다면 충전하고 바로 재시도하세요.