Error Codes - Extralt API

The Extralt API returns standard HTTP status codes with JSON error bodies.

Error response format

{
  "error": "ErrorType",
  "message": "Human-readable description of the error"
}

Authentication errors

Code	Error	Description	Solution
`401`	Unauthorized	Missing or invalid API key	Check your `Authorization: Bearer <key>` header
`403`	Forbidden	API key does not have access to this resource	Verify the key belongs to the correct organization

Validation errors

Code	Error	Description	Solution
`400`	Bad Request	Request body is malformed or missing required fields	Check the request body against the API docs
`404`	Not Found	The requested resource does not exist	Verify the resource ID is correct
`422`	Unprocessable Entity	Request is valid JSON but contains invalid values	Check field types and constraints

Rate limit errors

Code	Error	Description	Solution
`429`	Too Many Requests	Rate limit exceeded	Wait 15 seconds and retry. See Rate Limits

Resource errors

Code	Error	Description	Solution
`402`	Payment Required	Insufficient credits to perform the operation	Check your credit balance and upgrade if needed
`409`	Conflict	Resource already exists (e.g., duplicate robot build)	Use the existing resource instead

Server errors

Code	Error	Description	Solution
`500`	Internal Server Error	Unexpected server error	Retry the request. If persistent, contact support
`503`	Service Unavailable	Service temporarily unavailable	Wait and retry with exponential backoff

Handling errors in code

HTTP_STATUS=$(curl -s -o response.json -w "%{http_code}" \
  -X POST "$BASE_URL/runs" \
  -H "Authorization: Bearer $EXTRALT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"robotId\": \"$ROBOT_ID\", \"urls\": [\"$URL\"]}")

case $HTTP_STATUS in
  401) echo "Check your API key" ;;
  402) echo "Insufficient credits" ;;
  429) echo "Rate limited, retrying in 15s..."; sleep 15 ;;
  4*) jq '.message' response.json ;;
  *) jq '.' response.json ;;
esac