API 오류#

모든 API 실패는 동일한 응답 구조를 사용합니다. 메시지 텍스트가 아닌 error.code를 기준으로 분기하세요.

json

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Missing required parameter.",
    "param": "sql",
    "doc_url": "https://api.supernova.ai/docs#parameter_missing",
    "request_id": "req_..."
  }
}

Request-Id 응답 헤더에는 request_id와 같은 값이 포함됩니다. 지원팀에 문의할 때 이 값을 제공하세요. param은 입력 하나를 지정할 수 있을 때만 나타납니다.

상태 분류#

상태	의미	재시도 방법
`400`	잘못된 입력 또는 거부된 기능	요청 변경
`401`	자격 증명 누락, 형식 오류, 만료 또는 폐기	자격 증명 갱신 또는 교체
`403`	인증되었으나 권한 범위 또는 역할 부족	적절한 접근 권한 요청
`404`	리소스가 없거나 이 조직에서 볼 수 없음	다른 테넌트에 존재하는지 추론하지 않기
`409`	현재 상태가 작업과 충돌	현재 상태를 읽은 뒤 결정
`429`	호출자, 조직 또는 동시 실행 한도 도달	`Retry-After` 따르기
`500`	예기치 않은 서버 오류	멱등 요청이면 대기 시간을 늘리며 재시도
`503`	필요한 서비스 사용 불가	대기 시간을 늘리며 재시도

공통 코드#

코드	의미
`invalid_json`	본문이 유효한 JSON이 아님
`parameter_missing`	필수 입력 누락
`invalid_cursor`	커서가 해당 컬렉션에서 발급되지 않음
`invalid_format`	요청한 표현 형식을 지원하지 않음
`authentication_required`	bearer 자격 증명 누락
`invalid_token`	자격 증명 검증 실패
`insufficient_scope`	자격 증명에 엔드포인트의 권한 범위가 없음
`rate_limited`	요청 빈도 초과
`idempotency_key_reused`	키가 다른 입력에 연결되어 있음
`query_not_found`	이 조직에서 쿼리를 사용할 수 없음
`job_not_found`	이 조직에서 작업을 사용할 수 없음
`catalog_not_found`	스키마나 테이블이 없거나 숨겨져 있음
`source_not_found`	소스가 없거나 숨겨져 있음
`send_not_found`	전송 또는 해당 실행이 없거나 숨겨져 있음

리소스별 추가 코드는 해당 코드를 반환하는 작업 설명에 나와 있습니다.