KYC 없이 — 신분증, 셀피, 서류가 필요 없습니다. 암호화폐로 결제하세요: BTC, USDT, USDC, ETH, SOL, LTC
언어: 한국어
API 키 받기

문서 · API 레퍼런스

오류와 페이지 상태: 무엇이 실패했는지, 재시도해야 하는지

문제는 두 가지 종류가 있습니다. HTTP 오류는 호출 전체가 실패한 것이며 비용이 들지 않습니다. 페이지 상태는 검색은 성공했지만 한 페이지를 읽지 못한 경우로, 정상적인 200 응답 내부에 포함됩니다. 에이전트는 두 가지를 각각 다르게 처리해야 합니다.

마지막 업데이트: · 4 분 소요

빠른 답변

LLMWebSearch API는 어떤 오류를 반환할 수 있으며, 과금되나요?

LLMWebSearch에는 여섯 가지 HTTP 오류가 있습니다: 400 invalid_parameter, 401 invalid_api_key, 402 insufficient_credits, 429 rate_limited, 502 search_failed, 504 search_timeout. 어느 것도 과금되지 않습니다. 읽을 수 없는 페이지는 대신 200 응답 내부에 content_status로 표시됩니다. 정상적인 검색은 1 크레딧이 소모되며, 2026년 10월 기준 US$1.20/1K 검색입니다. KYC 없이 암호화폐로 결제하세요.

어떤 HTTP 오류가 있나요?

본문은 항상 {"error": {"code": "…", "message": "…"}}입니다. 어떤 오류도 크레딧을 사용하지 않습니다.

HTTPcode원인재시도?
400invalid_parameter필수 parameter가 없거나 값이 범위를 벗어남아니요: 요청을 수정하세요
401invalid_api_key키가 없거나, 잘못되었거나, 폐기됨아니요: 키를 확인하세요
402insufficient_credits잔액이 이 호출을 지불할 수 없음아니요: 팩을 구매하세요
429rate_limited계정이 허용하는 분당 호출 수 초과네, 잠시 후에
502search_failed검색을 완료할 수 없음네, 백오프로
504search_timeout30초 이내에 검색 결과 없음네, 백오프로

페이지 상태는 오류와 어떻게 다른가요?

페이지 상태는 호출이 아니라 개별 결과 하나를 설명합니다. 검색은 실행되었고 결과도 있으며 credits_used도 평소처럼 설정됩니다. 다만 그 한 페이지의 콘텐츠만 없고, content_status가 그 이유를 알려줍니다: blocked_by_robots, blocked_by_site_policy, target_refused, fetch_failed, fetch_timeout 또는 unsupported_content입니다.

이를 전체 검색을 다시 시도해야 하는 실패로 취급하지 마세요. 다른 결과나 누락된 페이지의 스니펫, 또는 다른 소스를 이용하세요. 응답 형식 페이지에 각 상태가 표로 설명되어 있습니다.

거부 응답에 대해 왜 재시도하지 않나요?

거부는 사이트의 답변이며, 저희는 이를 존중합니다. 저희 리더는 robots.txt를 준수합니다. 자신을 LLMWebSearch로 소개하고, 사이트가 리더를 위해 또는 모든 로봇을 위해 작성한 규칙을 따르며, 읽기가 허용되지 않은 페이지의 콘텐츠는 제외합니다. robots.txt에 Content-Signal: ai-input=no를 설정한 사이트는 해당 페이지의 콘텐츠가 결과에 포함되지 않습니다. 사이트가 저희 리더를 403, 429 또는 챌린지 페이지로 거부하면, target_status에 사이트 상태를 담아 target_refused로 보고합니다.

사이트가 저희 리더를 거부하면, 결과는 콘텐츠 없이 해당 사이트의 상태와 함께 반환됩니다. 저희는 CAPTCHA를 풀거나 계정에 로그인하거나 차단 또는 페이월을 우회하지 않습니다. 다른 신원이나 위장 브라우저로도 재시도하지 않습니다. 에이전트는 이런 페이지에서 반복 루프를 돌리지 않아야 합니다: 결과는 바뀌지 않고, 사이트가 이미 거절했기 때문입니다.

내 코드는 언제 재시도해야 하나요?

429, 502, 504에서만 하세요. 잠시 기다린 뒤 다시 시도하고, 대기 시간을 매번 두 배로 늘리며 약간의 무작위성을 더해 병렬 워커들이 같은 박자로 재시도하지 않게 하세요. 세 번에서 다섯 번 시도면 충분하며, 그 후에는 실패를 보고하세요.

400, 401 또는 402는 절대 재시도하지 마세요: 무언가를 바꾸기 전까지 같은 요청은 같은 답을 줍니다. 페이지의 경우 fetch_failed과 fetch_timeout은 나중에 새 검색이나 /extract 호출을 통해 성공할 수 있습니다. target_refused, blocked_by_robots, blocked_by_site_policy은 최종입니다.

Python: 429, 502, 504를 지수 백오프로 재시도
import os
import random
import time

import requests

API = "https://llmwebsearch.com/api/v1/search"
HEADERS = {"Authorization": "Bearer " + os.environ["LLMWEBSEARCH_API_KEY"]}
RETRY_ON = {429, 502, 504}


def search(body, attempts=5):
    delay = 1.0
    for attempt in range(1, attempts + 1):
        resp = requests.post(API, headers=HEADERS, json=body, timeout=60)
        if resp.status_code == 200:
            return resp.json()
        err = resp.json().get("error", {})
        if resp.status_code not in RETRY_ON or attempt == attempts:
            raise RuntimeError(f"{resp.status_code} {err.get('code')}: {err.get('message')}")
        time.sleep(delay + random.uniform(0, delay / 2))
        delay = min(delay * 2, 30)


data = search({"q": "how to rotate api keys without downtime"})
unread = [r["url"] for r in data["results"] if r["content_status"] not in ("ok", "not_requested")]
print("credits:", data["credits_used"], "| pages not read:", unread)

402 insufficient_credits가 나오면 어떻게 해야 하나요?

멈추고 충전하세요. 호출은 실행되지 않았고 비용도 들지 않았습니다. 긴 작업 도중에 멈추는 것을 피하려면 먼저 무료인 GET https://llmwebsearch.com/api/v1/credits로 잔액을 확인하고, 계획한 검색 횟수와 비교하세요. read이 3을 초과하는 검색은 크레딧 2개가 필요하다는 점을 기억하세요.

크레딧은 암호화폐 잔액으로 구매한 팩에서 나옵니다. 검색 크레딧에는 만료일이 없습니다. 이번 달에 사용하지 않은 크레딧은 내년에도 그대로 남아 있습니다.

rate limit 아래로 어떻게 유지하나요?

자체 코드에서 동시에 실행되는 호출 수를 제한하세요. 모든 계정에는 분당 호출 제한이 있으며 대시보드에 표시됩니다. 지원팀에 요청하면 상향할 수 있습니다. 대부분의 에이전트에는 4~8개의 작은 병렬 워커 풀이 폭주 없이 일정한 속도를 유지해 줍니다. Python과 Node.js 페이지에 각각 그런 풀이 나와 있습니다.

429을 받았다면 즉시 다음 시도를 쏘지 말고 잠시 멈추세요. 바로 재시도하면 거부되는 호출만 늘어납니다.

오류: 자주 묻는 질문

모든 페이지가 거부된 검색도 크레딧이 청구되나요?

네, 검색 자체가 작동했다면요: 순위가 매겨진 결과와 스니펫은 여전히 받습니다. 검색 가격은 그 페이지 중 몇 개를 읽을 수 있었는지에 달려 있지 않습니다.

401이 폐기된 키 때문에 발생하나요?

그럴 수 있습니다. 폐기된 키, 오타, 누락된 Bearer 접두사, 또는 저희에게 도달하지 못한 헤더 모두 401 invalid_api_key를 줍니다. 에이전트, 앱, 팀원별로 API 키를 하나씩 만들고, 다른 키는 건드리지 않고 대시보드에서 각각 폐기하세요.

페이지가 fetch_timeout을 반환한 이유는 무엇인가요?

페이지는 병렬로 읽히며, 15초를 넘는 페이지는 전체 응답을 지연시키지 않도록 콘텐츠 없이 반환됩니다. 느린 사이트는 나중 시도에서 응답하기도 합니다.

실패한 호출을 볼 수 있나요?

네. 대시보드 기록은 실패한 호출을 포함해 30일 동안 호출 내역을 상태와 크레딧과 함께 보여줍니다. 실패한 호출은 0 크레딧으로 표시됩니다.

US$1.20/1K 검색부터 · KYC 없이

API 키 받기