Troubleshooting

Fresh Source: docs.airtop.ai

Common errors, debugging tips, and session state reference.

HTTP Error Codes

Code	Meaning	Fix
400	Bad Request	Check request body parameters match the API schema
401	Unauthorized	Verify your API key is valid and correctly set
404	Not Found	Session or window may have expired/been terminated
422	Validation Error	Check request body against the API schema — often a missing required field
503	Service Unavailable	Retry with exponential backoff — temporary capacity issue

Session Issues

Session Stuck in "initializing"

Symptoms: Session never reaches "running" state.

Fixes:

• Check if your account has available capacity
• Try creating a session without proxy/captcha configuration
• Contact support if the issue persists

Session Terminated Unexpectedly

Symptoms: Session enters "ended" state before you terminated it.

Fixes:

• Check timeoutMinutes — default is 10 minutes, increase if needed
• Check for costThresholdCredits being hit
• Verify no other code is terminating the session

Session in "awaiting_capacity"

Symptoms: Session is waiting for a browser slot.

Fixes:

• Wait — capacity usually frees up within seconds
• Check your plan's concurrent session limits
• Terminate unused sessions to free capacity

Window Issues

Window Fails to Load URL

Symptoms: Window created but URL doesn't load.

Fixes:

• Verify the URL is accessible (not blocked, not behind VPN)
• Check if a proxy is needed for the target site
• Try waitUntil: 'domcontentloaded' instead of 'load' for slow pages

Window Not Found (404)

Symptoms: Operations fail with 404 on windowId.

Fixes:

• Check if the session is still running
• The window may have been closed — create a new one
• Verify you're using the correct sessionId/windowId pair

AI Operation Issues

pageQuery Returns Empty or Irrelevant Response

Fixes:

• Make your prompt more specific
• Ensure the page has fully loaded before querying
• Check if the content is behind a login (use profiles)
• Try scrolling down first if content is below the fold

fillForm Doesn't Fill All Fields

Fixes:

• Use more descriptive customData keys
• Check if some fields are hidden or in a different form section
• Try filling the form in multiple steps
• Verify the page has fully loaded

scrapeContent Returns Incomplete Content

Fixes:

• Wait for dynamic content to load
• Use waitUntil: 'load' when creating the window
• Scroll to trigger lazy-loaded content
• For paginated content, use paginatedExtraction

monitor Times Out Without Matching

Fixes:

• Verify the condition is achievable on that page
• Check if the page requires interaction to update (refresh, click)
• Increase timeoutMs if changes are infrequent
• Make the condition description clearer

Connection Issues

CDP/WebSocket Connection Failed

Symptoms: Playwright or Puppeteer can't connect.

Fixes:

• Ensure the session is in "running" state before connecting
• Check the CDP URL hasn't expired
• Verify network connectivity to Airtop's servers
• Try creating a fresh session

Live View URL Not Working

Fixes:

• Live View URLs are temporary and session-scoped
• Get a fresh URL with getWindowInfo
• Ensure the session is still running

Debugging Tips

1. Check Session State First

const info = await client.sessions.getInfo(sessionId);
console.log('Status:', info.data.status);

2. Use pageQuery to Inspect

const debug = await client.windows.pageQuery(sessionId, windowId, {
  prompt: 'Describe what is currently visible on this page, including any error messages.',
});
console.log(debug.data.modelResponse);

3. Take a Screenshot via Live View

const windowInfo = await client.windows.getWindowInfo(sessionId, windowId);
console.log('Open in browser:', windowInfo.data.liveViewUrl);

4. Check Credit Usage

If operations suddenly fail, you may have hit credit limits. Check the dashboard.

Session States Reference

initializing → awaiting_capacity → running → ended

State	Can Create Windows	Can Run AI Ops	Billed
initializing	No	No	No
awaiting_capacity	No	No	No
running	Yes	Yes	Yes (per 30s)
ended	No	No	No