Expand AI logo
DocsAPI ReferenceAPI Reference
Login

API Reference

Getting Started

API ReferenceRate LimitingError Handling

Endpoints

BatchedFetchFetch JsonFetch SearchGet Batched

Error Handling

Understanding API errors and how to handle them

The Expand API uses conventional HTTP response codes to indicate the success or failure of a request.

HTTP Status Codes

CodeDescription
200Success - The request completed successfully
400Bad Request - Invalid parameters or request body
401Unauthorized - Invalid or missing API key
429Too Many Requests - Rate limit exceeded
500Internal Error - Server error, includes fetch failures
503Service Unavailable - The service is temporarily unavailable

Error Response Format

All errors follow a consistent format with a _tag field identifying the error type:

{
  "_tag": "ErrorType",
  // Additional fields depend on error type
}

Error Types

Validation Errors (400)

Returned when the request body doesn't match the expected schema:

{
  "_tag": "HttpApiDecodeError",
  "message": "Invalid request parameters",
  "issues": [
    {
      "_tag": "Missing",
      "path": [

Common validation issues:

  • Missing required url field
  • Invalid URL format (must be http:// or https://)
  • Invalid regex pattern in include.links.includePatterns
  • Empty search.query

Authentication Errors (401)

Returned when authentication fails:

{
  "_tag": "AuthFailed",
  "reason": "InvalidApiKey",
  "description": "The provided API key is not valid"
}
ReasonDescription
InvalidApiKeyThe API key is missing or invalid
InvalidTokenThe bearer token is invalid
InvalidSessionThe session has expired
InvalidTenantThe organization was not found

Rate Limit Errors (429)

Returned when you exceed your rate limit. See Rate Limiting for details.

{
  "_tag": "TooManyRequests"
}

Fetch Errors (500)

Returned when content extraction fails:

{
  "_tag": "FetchError",
  "cause": "Navigation timeout: page took too long to load"
}

Common causes:

  • Target page is unreachable or blocked
  • Navigation timeout (page took too long to load)
  • Content capture failed
  • Screenshot capture failed

Service Errors (503)

Returned when the service is temporarily unavailable:

{
  "_tag": "ServiceUnavailable"
}

This typically indicates a temporary issue. Retry your request after a short delay.

Handling Errors

With SDKs

import Expand, { ExpandError, APIError, RateLimitError } from 'expandai'

const client = new Expand({ apiKey: '{{API_KEY}}' })

try {
  const result = await client.fetch({ url: 'https://example.com' })
} catch (error) {
  if (error instanceof RateLimitError) {
    // Handle rate limiting - wait and retry
    console.log('Retry after:', error.retryAfter)

With cURL

When using cURL or raw HTTP, check the response status code and parse the JSON body for error details:

response=$(curl -s -w "\n%{http_code}" -X POST https://api.expand.ai/v1/fetch \
  -H "x-expand-api-key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}')

status_code=$(echo "$response" | tail -n 1)
body=$(echo "$response

Best Practices

  1. Always check status codes before processing responses
  2. Log error details including the _tag field for debugging
  3. Implement retries for transient errors (429, 503)
  4. Validate inputs before making requests to avoid 400 errors
  5. Handle errors gracefully in your application to provide good user experience

On This Page

HTTP Status CodesError Response FormatError TypesValidation Errors (400)Authentication Errors (401)Rate Limit Errors (429)Fetch Errors (500)Service Errors (503)Handling ErrorsWith SDKsWith cURLBest Practices
"url"
],
"message": "is missing"
}
]
}
} else if (error instanceof APIError) {
// Handle API errors (4xx, 5xx)
console.log('Status:', error.status)
console.log('Message:', error.message)
} else if (error instanceof ExpandError) {
// Handle SDK errors
console.log('Error:', error.message)
}
}
from expandai import Expand, ExpandError, APIError, RateLimitError

client = Expand(api_key="{{API_KEY}}")

try:
    result = client.fetch(url="https://example.com")
except RateLimitError as e:
    # Handle rate limiting - wait and retry
    print(f"Retry after: {e.retry_after}")
except APIError as
"
| sed
'$d'
)
if [ "$status_code" -ne 200 ]; then
echo "Error ($status_code): $body"
fi
e:
# Handle API errors (4xx, 5xx)
print(f"Status: {e.status_code}, Message: {e.message}")
except ExpandError as e:
# Handle SDK errors
print(f"Error: {e.message}")