Errors

The API uses standard HTTP status codes to indicate success or failure of requests.

Status Codes

Error Response Format

All error responses follow this format:

{
  "error": "Error message describing what went wrong"
}

Common Error Scenarios

400 Bad Request

Returned when request parameters or body are invalid:

{
  "error": "Agent name must be URL-safe (alphanumeric, hyphens, underscores only)"
}

401 Unauthorized

Returned when the API key is missing or invalid:

{
  "error": "Unauthorized - Invalid or missing API key"
}

404 Not Found

Returned when the agent or deployment doesn't exist:

{
  "error": "No ready deployment found for this project"
}

502 Bad Gateway

Returned when the agent machine is unreachable:

{
  "error": "Unable to reach agent machine. The deployment may be down."
}

504 Gateway Timeout

Returned when the agent takes too long to respond (default timeout: 5 minutes):

{
  "error": "Request timeout - agent took too long to respond"
}