오류 코드 V5 (beta)

오류 응답의 모양과 모든 코드의 뜻입니다.

오류는 HTTP 상태와 함께 result: "error", 코드(code), 사람이 읽는 message, 필요하면 details로 옵니다. 프로그램은 code로 분기하세요 — message는 바뀔 수 있습니다. 기계가 읽는 명세는 OpenAPI(JSON)에도 있습니다.

오류 응답 모양

{
  "result": "error",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "code": "MISSING_PARAM",
  "message": "Required parameter is missing.",
  "elapsed_sec": 0.0011,
  "details": {
    "param_name": "when"
  }
}

{
  "result": "error",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "code": "INVALID_PARAM",
  "message": "Invalid parameter value.",
  "elapsed_sec": 0.0011,
  "details": {
    "param_name": "when",
    "errors": [
      "`type` must be one of interval, daily, days, weekly, monthly."
    ]
  }
}

코드 표

코드	HTTP	뜻과 할 일
`MISSING_API_KEY`	401	`Authorization` 헤더가 없습니다.
`INVALID_API_KEY`	401	API 키가 맞지 않습니다. 키를 다시 복사하세요.
`FORBIDDEN`	403	접근할 수 없습니다(예: 체험 계정의 봇은 바꿀 수 없음).
`MISSING_PARAM`	400	필수 값이 없습니다. `details.param_name`.
`INVALID_PARAM`	400	값이 맞지 않습니다. `details`의 `param_name`·`allowed`·`unknown_keys`·`errors`를 보세요.
`VALIDATION_FAILED`	400	저장 검증에 걸렸습니다. `details.errors`.
`RESOURCE_NOT_FOUND`	404	찾을 수 없습니다.
`BOT_NOT_FOUND`	404	봇이 없거나 접근할 수 없습니다(남의 봇·숨긴 봇 포함).
`PLAN_NOT_FOUND`	404	주기가 없거나 접근할 수 없습니다. 여러 주기 기능이 닫힌 계정은 주기 경로 전체가 이 코드입니다.
`DATASET_NOT_FOUND`	404	데이터셋이 없거나 접근할 수 없습니다.
`BULK_JOB_NOT_FOUND`	404	대량 수집의 접수 번호가 없거나 남의 것입니다. 접수 기록은 30일 보관합니다.
`TICKET_EXPIRED`	402	이용권이 만료됐거나 유효하지 않습니다.
`CREDIT_EXHAUSTED`	402	크레딧이 부족합니다. 충전한 뒤 새 키로 다시 요청하세요.
`EXECUTION_BLOCKED`	409	그 밖의 이유로 수집을 시작하지 못했습니다. `details.reason`.
`BOT_MAINTENANCE`	409	봇이 점검 중입니다. 잠시 뒤 다시 시도하세요.
`ALREADY_RUNNING`	409	재수집 대상이 이미 진행 중입니다. 새 수집은 겹쳐도 시작되므로 이 코드가 나오지 않습니다.
`IDEMPOTENCY_KEY_REQUIRED`	400	필수인 곳에 `Idempotency-Key` 헤더가 없습니다.
`IDEMPOTENCY_KEY_REUSED`	422	같은 키를 다른 내용의 요청에 썼습니다. 요청마다 새 키를 쓰세요.
`REQUEST_IN_PROGRESS`	409	같은 키의 첫 요청이 아직 처리 중입니다. 잠시 뒤 같은 키로 다시 보내세요.
`PLAN_CONDITION_BLOCKED`	422	이 봇은 주기마다(또는 이번만) 따로 조건을 둘 수 없습니다.
`PLAN_UNDELETABLE`	409	주기 1은 지울 수 없습니다. 끄기만 됩니다.
`PLAN_MODE_REFUSED`	422	이 봇은 주기 모드로 바꿀 수 없습니다. `details.reason`.
`PLAN_MODE_READONLY`	409	예약된 코드입니다. 지금 v5 는 보내지 않습니다.
`PLAN_NAME_TAKEN`	422	같은 이름의 주기가 이미 있습니다.
`EXCEL_NOT_SUPPORTED_YET`	422	엑셀 입력으로 수집하는 기능은 v5 에 아직 없습니다.
`EXCEL_FILE_REQUIRED`	422	엑셀 입력을 쓰려면 먼저 파일을 올려야 합니다.
`EXCEL_FILE_UNREADABLE`	422	올린 파일을 스프레드시트로 읽을 수 없습니다.
`WEBHOOK_NOT_SET`	422	이 봇에 웹훅 주소가 없어 테스트할 수 없습니다.
`RATE_LIMITED`	429	요청이 너무 잦습니다. 잠시 뒤 다시 시도하세요.
`INTERNAL_ERROR`	500	서버 오류입니다. `request_id`와 함께 문의해 주세요. 맡기기 전에 난 오류는 같은 키로 다시 보내도 됩니다.

오류 응답 모양

코드 표

함께 보면 좋은 가이드