Error handling guidelines

Recommended client behavior:

• Treat transport errors, HTTP errors and command failures separately.
• For POST /execute, a successful HTTP response only means the command was accepted into the queue.
• Always poll the command until done or failed.
• For batch results, inspect each item in response.commands.
• Handle offloaded_data_url wherever large outputs are possible.
• Clean up sessions in finally blocks so orphaned sessions do not keep billing.

Common failure sources:

• invalid command parameters
• unsupported proxy country or city
• session expiration or user-initiated stop while a command is pending
• large responses being offloaded rather than returned inline