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.

HTTP Status Codes

Statuses 520, 523, and 524 are part of granular Browse error codes, which are enabled by default.

Error Response Structure

All error responses follow this schema:

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

Authentication & Authorization Errors

Rate Limiting Errors

Browse API Specific Errors

Granular error codes are enabled by default for Browse. They identify the specific reason a page couldn't be returned, such as content filtering, a missing document, or a crawl failure, and include retry guidance where applicable. No opt-in or Support request is required.

Granular and legacy codes use the standard error response structure. Browse errors that aren't listed here are reported as InternalServerError (HTTP 500).

Legacy Browse error codes

These codes were used before granular error codes became the default. They're listed for reference when handling older responses.

Granular Browse error codes

When a retry delay applies, the response includes retryAfter as an ISO 8601 UTC timestamp in the format yyyy-MM-ddTHH:mm:ssZ, for example "retryAfter": "2026-10-30T01:01:00Z". Don't retry before that time. When retryAfter is omitted, no retry guidance applies.

Example granular error response:

{
  "errorCode": "URLFilteredOutEncumbrance",
  "errorCategory": "UserError",
  "userMessage": "The requested URL was filtered by content restrictions.",
  "retryAfter": "2026-10-31T01:00:00Z",
  "traceId": "0123456789abcdef0123456789abcdef"
}

Browse passage errors

These errors apply to Browse requests with contentFormat: "passage", including requests from applications without full document access, for which "passage" is the default format. See Browse passage requests.

All other Browse outcomes for passage requests use the same status codes and error codes as text, html, and markdown requests. That includes filtered pages, documents not found, a pending live crawl (202 Accepted), and crawl failures.

Service & Infrastructure Errors

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 AppID'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 (202) with url and retryAfter fields in the response body

Explanation: When liveCrawl is "fallback" and the URL isn't found in the index, the API can start a crawl asynchronously and return 202 Accepted. Live crawling is subject to publisher politeness restrictions and availability; "fallback" doesn't guarantee an actual crawl. The same behavior applies to every contentFormat, including passage.

Handling:

1. Check for HTTP status 202.
2. Read retryAfter from the response body. It's an ISO 8601 UTC timestamp (for example, "2026-10-30T01:01:00Z") that is the earliest time to retry.
3. Wait until that time.
4. Send the same request again. The url field contains the URL to request; it defaults to the URL you requested.
5. Limit the number of polling attempts. A crawl that can't complete eventually returns an error, such as HostCrawlTimeout (524) or FailedNoContent (520).

# 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", "contentFormat": "passage", "query": "information about this domain", "liveCrawl": "fallback"}'

# Example response when the URL isn't indexed: 202 Accepted with "retryAfter": "2026-10-30T01:01:00Z"
# Wait until that time, then send the same request again

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 until the retryAfter time and retry
5. Handle both retryAfter formats - Use the duration for AuthUserThrottled, AuthUserDailyUsageExceeded, and InternalServerError, and the ISO 8601 timestamp for Browse 202 and granular errors, including TooManyOnDemandCrawls (429)
6. Validate before sending - Check parameters locally to avoid 400 errors
7. Use HTTPS only - HTTP requests will return 410 errors