Microsoft Web IQ error handling

All v3 APIs return standardized error responses to help you diagnose and resolve issues quickly. This section covers HTTP status codes, error response structure, and common troubleshooting scenarios.

Note

All string enum values are case-insensitive.

HTTP Status Codes

Status Code	Applies To	Error Category	Description	Common Causes
200	All APIs	Success	The request succeeded.	-
202	Browse only	Accepted	Request accepted for processing (live crawl).	On-demand crawling in progress
400	All APIs	Bad Request	Invalid request parameters.	Missing required fields, invalid parameter values, malformed JSON
401	All APIs	Unauthorized	Authentication failed or missing.	Invalid API key, missing x-apikey header
403	All APIs	Forbidden	Valid credentials but insufficient permissions.	API key lacks required permissions
403	Browse only	Forbidden	Content filtered or URL excluded.	URL blocked by policy or content filtered
404	Browse only	Not Found	Document not found.	Invalid or inaccessible URL
410	All APIs	Gone	HTTPS required.	Request made over HTTP instead of HTTPS
415	All APIs	Unsupported Media Type	Content type not supported.	Missing or incorrect content-type header
429	All APIs	Too Many Requests	Rate limit exceeded.	Too many requests in time window
430	Browse only	Server Error	Too many on-demand crawls.	Excessive live crawl requests
500	All APIs	Internal Server Error	Unexpected server error.	Temporary server issue

Error Response Structure

All error responses follow this schema:

Field	Type	Description
errorCode	string	A more detailed error category that helps identify the type of error.
errorCategory	string	High-level category: UserError (client-side / non-retryable) or SystemError (server-side / retryable).
userMessage	string	Human-readable error description.
technicalDetails	string (optional)	Additional technical information or parameter validation details for debugging.
retryAfter	string (optional)	Time to wait before retrying.
requestId	string (optional)	Unique identifier for the request.
traceId	string	Distributed trace ID for debugging and Microsoft support.

Note

202 Accepted responses (e.g., Browse live crawl polling) are not error responses and do not use the error schema above. They may still include a retryAfter value to indicate when to retry the request.

Example Error Response:

{
  "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"
}

Error Codes Reference

Request Validation Errors

Error Code	HTTP Status	Category	Description
RequestInvalidFormat	400	UserError	Malformed JSON body or invalid request payload structure.
RequestInvalidMethod	400	UserError	Invalid method or tool name specified in request.
HandlerInvalidInput	400	UserError	Invalid input parameter values (e.g., empty query, maxResults out of range [1, 50], invalid enum values).
RequestBlockedHeader	400	UserError	Request contains a blocklisted debug/variant header (e.g., X-Augmentations, X-DebugOptions, X-XapHostOverride). Use documented URL parameters (?p1=, ?debugoptions=, ?atlahostname=) instead.
RequestUnsupportedMediaType	415	UserError	The content-type header is missing or not application/json.
MethodNotAllowed	405	UserError	HTTP method not permitted on the route (e.g., GET on a POST-only endpoint).

Authentication & Authorization Errors

Error Code	HTTP Status	Category	Description
AuthNoToken	401	UserError	Authentication required. No bearer token or API key provided.
AuthTokenParse	401	UserError	Invalid authentication token format or token parsing failed.
AuthInvalidApiKey	401	UserError	The provided API key is invalid or not recognized.
AuthenticationFailed	401	UserError	General authentication failure.
AuthExpiredTrial	401	UserError	The trial period has expired. Please upgrade your key.
AuthMissingEntryId	400	UserError	Missing application identity / entry ID in request context.
AuthUnauthorizedEntryId	401	UserError	Unauthorized entry ID. Application identity could not be resolved or requested ?APPID= is not in allowed list.
AuthUnauthorizedService	403	UserError	Caller is authenticated but unauthorized to access the requested service/vertical.
AuthBatchEndpointRequired	403	UserError	Application is required to use the batch endpoint (X-FD-Batch: 1) for web search.
AuthMcpWebForbidden	403	UserError	Application is not permitted to use the MCP web tool.

Rate Limiting Errors

Error Code	HTTP Status	Category	Description
AuthUserThrottled	429	UserError	Request frequency exceeds your resource's rate limit. Check retryAfter.
AuthUserDailyUsageExceeded	429	UserError	Daily request quota has been reached (resets at 00:00 UTC). Check retryAfter.

Browse API Specific Errors

Error Code	HTTP Status	Category	Description
BrowseApiDocNotFound	404	UserError	Document not found. No content available for the specified URL.
BrowseApiIsFilteredOut	403	UserError	Result was dropped due to policy or content filtering.
BrowseApiIsUrlExcluded	403	UserError	The target URL is excluded or disallowed by policy.
BrowseApiTooManyOnDemandCrawls	430	UserError	Too many on-demand live crawl requests in progress.

Service & Infrastructure Errors

Error Code	HTTP Status	Category	Retryable	Description
InternalServerError	500	SystemError	Yes (30s)	Internal server error.

Common Error Scenarios

Authentication errors (401, 403)

Symptom: Authentication failed or forbidden access

Solutions:

• Verify your API key is correct and included in the x-apikey header
• Check that your API key has not expired
• Ensure you have the required permissions for the endpoint
• Contact your Microsoft representative if issues persist

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"}'

Rate limiting (429)

Symptom: Rate limit exceeded or daily quota exhausted (AuthUserThrottled or AuthUserDailyUsageExceeded)

Requests above your resource's rate limit return HTTP 429. Your rate limit is shown in the Web IQ portal.

Solutions:

• Implement exponential backoff retry logic
• Wait for the retryAfter interval in the error response (e.g., "60s") before retrying
• Reduce request frequency
• Note that daily quota caps (AuthUserDailyUsageExceeded) reset daily at 00:00 UTC
• To request a higher limit, contact Web IQ Support

Example Response:

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

Invalid parameters (400)

Symptom: Bad request due to invalid parameters

Common Issues:

• Required fields missing (e.g., query parameter)
• Parameter values out of range (e.g., maxResults > 50)
• Invalid parameter types (e.g., string instead of integer)
• Unsupported parameter values (e.g., invalid contentFormat)

Solutions:

• Validate all required parameters are present
• Check parameter values against documented constraints
• Ensure proper JSON formatting

Server and infrastructure errors (500)

Symptom: Unexpected internal server or upstream service error (InternalServerError)

Solutions:

• Check the retryAfter field (defaults to "30s") and retry the request after waiting
• Implement retry with exponential backoff and jitter
• If the issue persists, contact Microsoft support with the traceId provided in the response

Example Response:

{
  "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"
}

Browse API accepted response (202)

Symptom: Accepted response with retryAfter field

Explanation: When liveCrawl is set to "fallback" and the URL needs to be crawled, the API returns 202 Accepted with a retryAfter value indicating when to retry the request.

Handling:

# 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

Best practices

1. Always check status codes - Don't assume success
2. Use traceId for support - Include traceId when contacting support
3. Implement retry logic - Use exponential backoff for transient errors
4. Handle 202 responses - For Browse API with live crawl, wait and retry
5. Validate before sending - Check parameters locally to avoid 400 errors
6. Use HTTPS only - HTTP requests will return 410 errors