외부 시스템 연동
오류와 재시도
API 조회가 실패했을 때 상태 코드별로 확인하고 재시도하는 방법입니다.
외부 API의 요청은 모두 읽기 전용입니다. 조회가 실패하면 HTTP 상태 코드와 오류 응답의 error.code를 먼저 확인하세요. 키나 조회 조건이 잘못된 요청은 반복해서 보내도 해결되지 않습니다.
상태 코드별 대응
| 상태 코드 | 확인할 내용 | 다음 행동 |
|---|---|---|
400 | SKU·위치 ID 형식, 조회 조건, 페이지 커서 | 잘못된 값을 수정합니다. 커서를 사용할 때는 이전 요청의 필터를 유지합니다. |
401 | 개발자 키 누락·오입력·만료·폐기 여부 | Authorization 헤더를 확인하고, 관리자에게 키 상태를 확인합니다. 자동 재시도하지 않습니다. |
403 | billing_access_restricted: 워크스페이스 이용 정지 | 자동 재시도하지 않습니다. 조직 관리자에게 대시보드 정산에서 정지 사유와 필요한 조치를 확인해 달라고 요청하고, 이용 복구를 확인한 뒤 다시 조회합니다. |
404 | SKU, 위치, 이벤트가 해당 워크스페이스에 있는지 | 목록 API에서 ID를 다시 확인합니다. |
429 | 요청 횟수 제한 | Retry-After에 표시된 초만큼 기다린 뒤 재시도합니다. 병렬 요청 수나 조회 주기도 줄입니다. |
503 | 일시적인 조회 서비스 장애 | 대기 시간을 늘려가며 제한된 횟수만 재시도합니다. 계속 실패하면 지원팀에 문의합니다. |
입력 형식이나 허용 범위를 벗어나면 400과 invalid_external_request가 반환됩니다. 오류 메시지에 입력값이 포함되지 않으므로 요청의 ID 형식·페이지 크기·필터를 확인하세요.
400의 invalid_external_*_cursor 오류는 cursor가 다른 워크스페이스, 대상 이벤트, 또는 필터에서 왔다는 뜻입니다. 같은 조회 조건에 앞서 받은 page.nextCursor를 전달하세요. 네트워크 연결이 끊기거나 응답 시간이 초과된 경우에도 조회 요청을 다시 보낼 수 있습니다. 무한히 반복하지 말고 최대 시도 횟수와 전체 대기 시간을 정하세요. Retry-After가 없다면 재시도 간격을 점차 늘립니다.
오류 응답
{
"error": {
"code": "invalid_workspace_token",
"message": "Workspace token is missing or invalid."
}
}전체 상태 코드와 응답 구조는 외부 API 명세에서 확인할 수 있습니다.
지원 요청에 포함할 정보
문제가 계속되면 발생 시각, 요청 경로, HTTP 상태 코드, error.code, 재시도 횟수를 알려주세요. 요청 ID를 기록했다면 함께 전달하세요. 개발자 키, 전체 Authorization 헤더, 비밀번호와 개인정보는 로그나 지원 요청에 포함하지 마세요.