API 개요

Base URL

https://openapi.thunderbit.com/openapi/v1

인증

모든 엔드포인트는 HTTP Bearer(API Key)를 사용합니다:

Authorization: Bearer YOUR_API_KEY

Thunderbit 대시보드에서 키를 발급받으세요. 키는 폐기 가능하며 환경별로 분리됩니다 —— 운영 키를 클라이언트 코드에 절대 포함시키지 마세요.

오류 응답 구조

모든 오류 응답은 동일한 envelope를 공유합니다. 기본값은 LEGACY 형식입니다:

{
  "success": false,
  "error": {
    "code":    "INVALID_URL",
    "status":  400,
    "message": "The provided URL is not valid",
    "details": null
  }
}

Note: 이전에 GOOGLE_RPC 대체 엔벨로프가 문서화되어 있었고, code와 status의 타입이 서로 바뀌었습니다 (string ↔ number). 이 모드는 사용을 권장하지 않으며 deprecated 입니다 — 강타입 클라이언트(OpenAPI codegen, Pydantic, serde, encoding/json)는 역직렬화에 실패합니다. 위 LEGACY 형식을 사용하세요. 향후 업데이트에서도 code: string, status: number 가 유지됩니다. details 필드는 구조화된 컨텍스트를 담을 수 있습니다 —— 예를 들어 INVALID_PARAMETER 시에는 { field: message } 형식의 필드 단위 검증 오류가 반환됩니다.

표준 오류 코드

HTTP	Code	의미
400	`INVALID_URL`	URL 형식이 잘못됨
400	`INVALID_SCHEMA`	JSON Schema가 잘못됨
400	`INVALID_PARAMETER`	하나 이상의 요청 파라미터 검증 실패
400	`SCHEMA_OR_PROMPT_REQUIRED`	추출 시 `schema`(또는 `prompt`) 필수
400	`SCHEMA_AND_PROMPT_EXCLUSIVE`	`schema`와 `prompt`는 동시에 제공할 수 없음
400	`BATCH_SIZE_EXCEEDED`	배치 요청이 100 URL 상한을 초과
400	`MALFORMED_REQUEST_BODY`	요청 본문이 유효한 JSON이 아님
401	`API_KEY_MISSING`	`Authorization` 헤더 누락
401	`API_KEY_INVALID_FORMAT`	API Key 형식이 잘못됨
401	`API_KEY_NOT_FOUND`	시스템에서 API Key를 찾을 수 없음
401	`API_KEY_REVOKED`	API Key가 폐기됨
401	`API_KEY_DISABLED`	API Key가 비활성화됨
401	`API_KEY_EXPIRED`	API Key가 만료됨
401	`INVALID_API_KEY`	(사용 중단, 위의 구체적 `API_KEY_` 코드 사용 권장)*
402	`INSUFFICIENT_CREDITS`	계정 크레딧 부족
404	`JOB_NOT_FOUND`	배치 작업을 찾을 수 없음
404	`RESOURCE_NOT_FOUND`	리소스를 찾을 수 없음
408	`REQUEST_TIMEOUT`	API 요청 타임아웃
408	`SCRAPE_TIMEOUT`	대상 페이지 응답 타임아웃
422	`SCRAPE_SSL_ERROR`	대상 사이트의 SSL/TLS 문제
422	`SCRAPE_DNS_RESOLUTION_ERROR`	대상 호스트명 해석 실패
422	`SCRAPE_SITE_ERROR`	대상 사이트가 오류 반환
422	`SCRAPE_EMPTY_CONTENT`	대상 페이지가 빈 콘텐츠 반환
422	`SCRAPE_CONTENT_TOO_LARGE`	대상 페이지가 크기 한도 초과
422	`SCRAPE_TARGET_FORBIDDEN`	대상 사이트 접근 거부(403)
422	`SCRAPE_TARGET_NOT_FOUND`	대상 URL이 404 반환
422	`SCRAPE_UNSUPPORTED_FILE`	지원하지 않는 파일 형식
429	`RATE_LIMIT_EXCEEDED`	계정 속도 제한 발동
429	`SCRAPE_TARGET_RATE_LIMITED`	대상 사이트가 요청에 속도 제한 적용
500	`INTERNAL_ERROR`	일반 내부 오류
500	`DISTILL_FAILED`	디스틸 파이프라인 실패
500	`EXTRACT_FAILED`	추출 파이프라인 실패
500	`PIPELINE_ERROR`	파이프라인 단계 실패
500	`AI_EXTRACTION_FAILED`	AI 추출 단계 실패
500	`MARKDOWN_CONVERSION_FAILED`	HTML → Markdown 변환 실패
502	`SCRAPE_ALL_PROVIDERS_FAILED`	모든 스크레이핑 provider 실패
502	`UPSTREAM_BAD_GATEWAY`	업스트림이 잘못된 응답 반환
503	`SCRAPE_PROVIDER_UNAVAILABLE`	스크레이핑 provider 사용 불가
503	`AI_SERVICE_UNAVAILABLE`	AI 서비스 사용 불가
503	`DOWNSTREAM_SERVICE_UNAVAILABLE`	다운스트림 서비스 일시 사용 불가
504	`UPSTREAM_TIMEOUT`	업스트림 게이트웨이 타임아웃
504	`AI_TIMEOUT`	AI 서비스 호출 타임아웃

재시도 전략 참조

오류 분류	재시도?	방법
`4xx`(입력 오류)	❌ 불가	요청 수정 후 재시도
`401`(인증)	❌ 불가	API Key 재발급 / 교체
`402`(크레딧)	❌ 불가	충전
`408` / `504`(타임아웃)	✅ 가능	지수 백오프, 최대 3회
`429`(속도 제한)	✅ 가능	`X-RateLimit-Reset`까지 대기 —— 속도 제한 참고
`5xx`(서버)	✅ 가능	지수 백오프, 최대 3회
`SCRAPE_TARGET_*`(대상 사이트)	⚠️ 경우에 따라	`renderMode`를 올려 1회 재시도

API 개요

Base URL

인증

오류 응답 구조

표준 오류 코드

재시도 전략 참조

On this page