Microsoft Web IQ 오류 처리

모든 v3 API는 문제를 신속하게 진단하고 해결하는 데 도움이 되도록 표준화된 오류 응답을 반환합니다. 이 섹션에서는 HTTP 상태 코드, 오류 응답 구조 및 일반적인 문제 해결 시나리오에 대해 설명합니다.

Note

모든 문자열 열거형 값은 대/소문자를 구분하지 않습니다.

HTTP 상태 코드

상태 코드	적용 대상	오류 범주	Description	일반적인 원인
200	모든 API	Success	요청이 성공했습니다.	-
202	찾아보기 전용	수락됨	처리 요청이 수락되었습니다(라이브 크롤링).	진행 중인 주문형 크롤링
400	모든 API	잘못된 요청	잘못된 요청 매개 변수입니다.	필수 필드 누락, 잘못된 매개 변수 값, 형식이 잘못된 JSON
401	모든 API	권한 없음	인증이 실패했거나 누락되었습니다.	잘못된 API 키, x-apikey 헤더 누락
403	모든 API	사용할 수 없음	유효한 자격 증명이지만 권한이 부족합니다.	API 키에 필요한 권한이 없음
403	찾아보기 전용	사용할 수 없음	필터링된 콘텐츠 또는 URL이 제외되었습니다.	필터링된 정책 또는 콘텐츠에 의해 차단된 URL
404	찾아보기 전용	찾을 수 없음	문서를 찾을 수 없습니다.	잘못되었거나 액세스할 수 없는 URL
410	모든 API	사라졌다	HTTPS가 필요합니다.	HTTPS 대신 HTTP를 통해 요청
415	모든 API	지원되지 않는 미디어 형식	콘텐츠 형식은 지원되지 않습니다.	헤더 누락 또는 잘못된 `content-type` 헤더
429	모든 API	요청이 너무 많음	속도 제한을 초과했습니다.	시간 창에 요청이 너무 많습니다.
430	찾아보기 전용	서버 오류	주문형 크롤링이 너무 많습니다.	과도한 라이브 크롤링 요청
500	모든 API	내부 서버 오류	예기치 않은 서버 오류가 발생했습니다.	임시 서버 문제

오류 응답 구조

모든 오류 응답은 다음 스키마를 따릅니다.

Field	Type	Description
`errorCode`	string	오류 유형을 식별하는 데 도움이 되는 보다 자세한 오류 범주입니다.
`errorCategory`	string	상위 수준 범주: `UserError` (클라이언트 쪽/다시 시도할 수 없음) 또는 `SystemError` (서버 쪽/다시 시도 가능).
`userMessage`	string	사람이 읽을 수 있는 오류 설명입니다.
`technicalDetails`	문자열(선택 사항)	디버깅을 위한 추가 기술 정보 또는 매개 변수 유효성 검사 세부 정보입니다.
`retryAfter`	문자열(선택 사항)	다시 시도하기 전에 대기할 시간입니다.
`requestId`	문자열(선택 사항)	요청에 대한 고유 식별자입니다.
`traceId`	string	디버깅 및 Microsoft 지원을 위한 분산 추적 ID입니다.

Note

202 Accepted 응답(예: 라이브 크롤링 폴링 찾아보기)은 오류 응답이 아니며 위의 오류 스키마를 사용하지 않습니다. 요청을 다시 시도할 시기를 나타내는 값이 계속 포함될 retryAfter 수 있습니다.

오류 응답 예제:

{
  "errorCode": "HandlerInvalidInput",
  "errorCategory": "UserError",
  "userMessage": "Invalid input provided. Please check your request parameters.",
  "technicalDetails": "Parameter validation failed: maxResults=100 exceeds maximum=50",
  "requestId": "req_abc123",
  "traceId": "trace_xyz789"
}

오류 코드 참조

유효성 검사 오류 요청

오류 코드	HTTP 상태	Category	Description
`RequestInvalidFormat`	400	`UserError`	형식이 잘못된 JSON 본문 또는 잘못된 요청 페이로드 구조입니다.
`RequestInvalidMethod`	400	`UserError`	요청에 지정된 메서드 또는 도구 이름이 잘못되었습니다.
`HandlerInvalidInput`	400	`UserError`	잘못된 입력 매개 변수 값(예: 빈 쿼리, `maxResults` 범위 [1, 50], 잘못된 열거형 값)
`RequestBlockedHeader`	400	`UserError`	요청에는 차단 목록의 디버그/변형 헤더(예: , `X-Augmentations`, `X-DebugOptionsX-XapHostOverride`)가 포함됩니다. 대신 문서화된 URL 매개 변수(`?p1=`, `?debugoptions=`, `?atlahostname=`)를 사용합니다.
`RequestUnsupportedMediaType`	415	`UserError`	`content-type` 헤더가 누락되었거나 없습니다`application/json`.
`MethodNotAllowed`	405	`UserError`	경로에서 허용되지 않는 HTTP 메서드(예: POST 전용 엔드포인트의 GET).

인증 및 권한 부여 오류

오류 코드	HTTP 상태	Category	Description
`AuthNoToken`	401	`UserError`	인증이 필요합니다. 전달자 토큰 또는 API 키가 제공되지 않았습니다.
`AuthTokenParse`	401	`UserError`	잘못된 인증 토큰 형식 또는 토큰 구문 분석이 실패했습니다.
`AuthInvalidApiKey`	401	`UserError`	제공된 API 키가 잘못되었거나 인식되지 않습니다.
`AuthenticationFailed`	401	`UserError`	일반 인증 실패.
`AuthExpiredTrial`	401	`UserError`	평가 기간이 만료되었습니다. 키를 업그레이드하세요.
`AuthMissingEntryId`	400	`UserError`	요청 컨텍스트에서 애플리케이션 ID/항목 ID가 누락되었습니다.
`AuthAppIdSelectionRequired`	400	`UserError`	ID는 여러 애플리케이션에 매핑됩니다. 쿼리 매개 변수를 사용하여 대상 애플리케이션을 `APPID` 지정합니다. 둘 이상의 AppID 호출을 참조하세요.
`AuthUnauthorizedEntryId`	401	`UserError`	권한이 없는 항목 ID입니다. 애플리케이션 ID를 확인할 수 없거나 API 키 인증을 사용하여 `APPID` 쿼리 매개 변수를 보냈습니다.
`AuthUnauthorizedAppId`	403	`UserError`	지정된 `APPID` ID가 사용자 ID와 연결되어 있지 않습니다.
`AuthUnauthorizedService`	403	`UserError`	호출자는 인증되었지만 요청된 서비스/수직 서비스에 액세스할 수 없습니다.
`AuthBatchEndpointRequired`	403	`UserError`	애플리케이션은 웹 검색에 일괄 처리 엔드포인트(`X-FD-Batch: 1`)를 사용해야 합니다.
`AuthMcpWebForbidden`	403	`UserError`	애플리케이션은 MCP `web` 도구를 사용할 수 없습니다.
`AuthContentFormatForbidden`	403	`UserError`	이 애플리케이션은 구절에만 액세스할 수 있습니다. 를 사용합니다 `contentFormatpassage`. 구절 및 콘텐츠 형식을 참조하세요.

속도 제한 오류

오류 코드	HTTP 상태	Category	Description
`AuthUserThrottled`	429	`UserError`	요청 빈도가 리소스의 속도 제한을 초과합니다. `retryAfter`를 확인합니다.
`AuthUserDailyUsageExceeded`	429	`UserError`	일일 요청 할당량에 도달했습니다(UTC 00:00에 다시 설정). `retryAfter`를 확인합니다.

API 관련 오류 찾아보기

오류 코드	HTTP 상태	Category	Description
`BrowseApiDocNotFound`	404	`UserError`	문서를 찾을 수 없습니다. 지정된 URL에 사용할 수 있는 콘텐츠가 없습니다.
`BrowseApiIsFilteredOut`	403	`UserError`	정책 또는 콘텐츠 필터링으로 인해 결과가 삭제되었습니다.
`BrowseApiIsUrlExcluded`	403	`UserError`	대상 URL은 정책에 의해 제외되거나 허용되지 않습니다.
`BrowseApiTooManyOnDemandCrawls`	430	`UserError`	진행 중인 주문형 라이브 크롤링 요청이 너무 많습니다.

서비스 및 인프라 오류

오류 코드	HTTP 상태	Category	다시 시도 가능	Description
`InternalServerError`	500	`SystemError`	예(30대)	내부 서버 오류입니다.

일반적인 오류 시나리오

인증 오류(401, 403)

증상: 인증 실패 또는 액세스 금지

솔루션:

API 키가 올바르고 헤더에 x-apikey 포함되어 있는지 확인합니다.
API 키가 만료되지 않았는지 확인합니다.
엔드포인트에 필요한 권한이 있는지 확인합니다.
문제가 지속되면 Microsoft 담당자에게 문의하세요.

Example:

# Correct authentication
curl -X POST "https://api.microsoft.ai/v3/search/web" \
  -H "x-apikey: your-valid-key-here" \
  -H "content-type: application/json" \
  -d '{"query": "test"}'

속도 제한(429)

증상: 속도 제한이 초과되었거나 일일 할당량이 소진됨(AuthUserThrottled 또는 AuthUserDailyUsageExceeded)

리소스의 속도 제한을 초과하는 요청은 HTTP 429를 반환합니다. 속도 제한은 Web IQ 포털에 표시됩니다.

솔루션:

지수 백오프 재시도 로직 구현
retryAfter 다시 시도하기 전에 오류 응답의 간격(예: "60s")을 기다립니다.
요청 빈도 감소
일일 할당량 한도()는AuthUserDailyUsageExceeded 매일 00:00 UTC로 다시 설정됩니다.
더 높은 제한을 요청하려면 Web IQ 지원에 문의하세요.

응답 예제:

{
  "errorCode": "AuthUserThrottled",
  "errorCategory": "UserError",
  "userMessage": "Rate limit exceeded. Please reduce your request frequency.",
  "retryAfter": "60s",
  "requestId": "req_123",
  "traceId": "trace_456"
}

잘못된 매개 변수(400)

증상: 잘못된 매개 변수로 인해 잘못된 요청

일반적인 문제:

필수 필드 누락(예: query 매개 변수)
범위를 벗어난 매개 변수 값(예: maxResults> 50)
잘못된 매개 변수 형식(예: 정수 대신 문자열)
지원되지 않는 매개 변수 값(예: 유효하지 않음 contentFormat)

솔루션:

모든 필수 매개 변수가 있는지 확인
문서화된 제약 조건에 대한 매개 변수 값 확인
적절한 JSON 서식 지정 확인

서버 및 인프라 오류(500)

증상: 예기치 않은 내부 서버 또는 업스트림 서비스 오류(InternalServerError)

솔루션:

retryAfter 필드를 확인하고(기본값: "30s") 대기한 후 요청을 다시 시도합니다.
지수 백오프 및 지터를 사용하여 재시도 구현
문제가 지속되면 응답에 제공된 Microsoft 지원에 traceId 문의하세요.

응답 예제:

{
  "errorCode": "InternalServerError",
  "errorCategory": "SystemError",
  "userMessage": "The service is temporarily unavailable. Please try again later.",
  "technicalDetails": "An internal service error occurred. Please contact support if the issue persists.",
  "retryAfter": "30s",
  "traceId": "trace_456"
}

찾아보기 API 수락 응답(202)

증상: 필드가 있는 retryAfter 수락된 응답

설명: "대체"로 설정되고 URL을 크롤링해야 하는 경우 liveCrawl API는 요청을 다시 시도할 시기를 나타내는 값으로 retryAfter 202 Accepted를 반환합니다.

취급:

# Initial request
curl -X POST "https://api.microsoft.ai/v3/browse" \
  -H "x-apikey: your-key" \
  -H "content-type: application/json" \
  -d '{"url": "https://example.com", "liveCrawl": "fallback"}'

# Response: 202 Accepted with retryAfter
# Wait for the specified time, then retry the same request

모범 사례

항상 상태 코드 확인 - 성공을 가정하지 마세요.
지원에 traceId 사용 - 지원에 문의할 때 traceId 포함
재시도 논리 구현 - 일시적인 오류에 지수 백오프 사용
202개 응답 처리 - 라이브 크롤링을 사용하여 API 찾아보기, 대기 및 다시 시도
보내기 전에 유효성 검사 - 400 오류를 방지하기 위해 로컬로 매개 변수 확인
HTTPS만 사용 - HTTP 요청이 410 오류를 반환합니다.

피드백

이 페이지가 도움이 되었나요?

2026-10-19 에 마지막으로 업데이트됨

Microsoft Web IQ 오류 처리

HTTP 상태 코드

오류 응답 구조

오류 코드 참조

유효성 검사 오류 요청

인증 및 권한 부여 오류

속도 제한 오류

API 관련 오류 찾아보기

서비스 및 인프라 오류

일반적인 오류 시나리오

인증 오류(401, 403)

속도 제한(429)

잘못된 매개 변수(400)

서버 및 인프라 오류(500)

찾아보기 API 수락 응답(202)

모범 사례

피드백

추가 리소스