사용 규칙
에러
모든 에러는 같은 형식으로 옵니다. HTTP 상태보다 code 값으로 분기하세요.
에러 형식
에러 응답
{
"error": {
"code": "range_too_large",
"message": "조회 기간은 최대 31일입니다.",
"request_id": "req_01J8XQ4M2N7P"
}
}request_id 는 문의할 때 반드시 함께 알려주세요. 이 값으로 서버 로그를 특정할 수
있습니다. message 는 사람이 읽기 위한 것이며 예고 없이 바뀔 수 있습니다 — 파싱하지 마세요.
에러 코드
| 상태 | code | 뜻 |
|---|---|---|
| 400 | invalid_request | 파라미터가 없거나 형식이 잘못됨 |
| 400 | range_too_large | 조회 기간이 31일을 넘음 |
| 400 | invalid_cursor | 커서가 손상되었거나 다른 조회 조건과 함께 쓰임 |
| 401 | invalid_token | 토큰이 없거나 서명이 맞지 않음 |
| 401 | token_expired | 토큰이 만료됨. 재발급 후 재시도 |
| 403 | insufficient_scope | 토큰에 필요한 스코프가 없음 |
| 403 | account_suspended | 계정이 정지됨 |
| 404 | store_not_found | 없는 매장이거나 연결되지 않은 매장 |
| 404 | staff_not_found | 없는 직원이거나 권한 밖 |
| 404 | record_not_found | 없는 기록이거나 권한 밖 |
| 429 | rate_limited | 한도 초과. Retry-After 확인 |
| 500 | internal_error | 서버 오류. request_id 와 함께 문의 |
| 503 | upstream_unavailable | 일시적 장애. 백오프 후 재시도 |
404 에 대하여
i
없는 것과 권한 없는 것을 구분하지 않습니다
연결되지 않은 매장을 조회하면 403 이 아니라 404 가 옵니다. 403 을 주면 "그 매장이 기그를
쓴다" 는 사실이 드러나기 때문입니다. 다른 사업자의 정보이므로 존재 여부 자체를 알려주지
않습니다.
따라서 404 를 받았을 때는 매장 id 오류와 연결 해제 둘 다
의심해야 합니다. /stores 로 현재 연결 목록을 다시 확인하세요.
재시도
- 재시도해도 되는 것 — 429, 500, 502, 503, 504, 네트워크 오류
- 재시도하면 안 되는 것 — 400, 403, 404. 요청을 고치지 않는 한 결과가 같습니다
- 401 — 토큰을 재발급한 뒤 한 번만 재시도합니다
백오프
// 지수 백오프 + 지터. 429 는 Retry-After 를 우선한다.
const delay = Math.min(1000 * 2 ** attempt, 60_000) * (0.5 + Math.random() * 0.5);